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Preface 


Intended Audience 


This manual describes the language elements and syntax of VAX BASIC. 
Readers are presumed to be familiar with VAX BASIC programming tech- 
niques. This manual provides reference material to be used in conjunction 
with the other two manuals in the documentation set. 


Associated Documents 


This manual is one of three manuals that form the VAX BASIC document 
set. The other two manuals are as follows: 


VAX BASIC User Manual Provides tutorial material for VAX BASIC 
language constructs and information 
pertaining to programming with VAX 
BASIC on VAX/VMS systems 

Programming with VAX BASIC Provides tutorial and reference material on 

Graphics VAX BASIC graphics capabilities 


You may also be interested in the following supplementary manuals: 
e VAX BASIC Syntax Summary 

e Introduction to BASIC 

e BASIC for Beginners 

e More BASIC for Beginners 


July 1988 XV 


Document Structure 


This manual consists of four chapters and four appendixes. 


Chapter 1 
Chapter 2 
Chapter 3 
Chapter 4 
Appendix A 


Appendix B 


Appendix C 
Appendix D 


Summarizes VAX BASIC program elements and structure 
Describes VAX BASIC environment commands 

Describes VAX BASIC compiler directives 

Describes VAX BASIC statements and functions 


Summarizes transportability issues between BASIC-PLUS-2 
and VAX BASIC 


Explains how VAX BASIC conforms to the ANSI Minimal 
Standard for BASIC 


Lists the ASCII codes 
Lists VAX BASIC keywords 


In Chapters 2, 3, and 4, the VAX BASIC language elements are arranged 
in alphabetical order within each part; each language element begins on 
a separate page. These chapters provide reference material on each VAX 
BASIC language element. The descriptions are arranged in alphabetical 

order and include the following sections: 


Overview 
Format 
Syntax Rules 


Example 


xvi 


An overview of what the statement or command does. 
The required syntax for the language element. 


Any rules governing the use of parameters, separators, or other 
syntax items, effect of the statement or command on program 
execution, and any restrictions governing its use. 


One or more examples of the statement in a partial program. 
Where appropriate, explanatory text and program output are 
included. 
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Conventions Used in This Document 


This manual uses case of text, symbols, and mnemonics in syntactical 
diagrams. This symbology aids in providing more concise and exact 
descriptions of syntatic variables, rules, and format. 


Convention 
$ BASIC 


UPPERCASE letters 


lowercase letters 


[] 


Meaning 


In command-line examples, the user’s response to a 
system prompt is printed in red; system prompts are 
printed in black. 


Uppercase letters are used for VAX BASIC keywords and 
must be coded exactly as shown. 


Lowercase letters are used to indicate user-supplied names 
or characters. 


Brackets enclose an optional portion of a format. Brackets 
around vertically stacked items indicate that you can 
select one of the enclosed items. You must include all 
punctuation as it appears in the brackets. 


Braces enclose a mandatory portion of a format. Braces 
around vertically stacked items indicate that you must 
choose one of the enclosed items. You must include all 
punctuation as it appears in the braces. 


A vertical ellipsis indicates that code which would nor- 
mally be present is not shown. 


An ellipsis indicates that the immediately preceding item 
can be repeated. An ellipsis following a format unit 
enclosed in brackets or braces means that you can repeat 
the entire unit. If repeated items or format units must be 
separated by commas, the ellipsis is preceded by a comma 


(od): 
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The following mnemonics are used in the syntax diagrams: 


Mnemonic 


angle 


array 


chnl 
com 


cond 


const 
data-type 
def 

exp 
file-spec 
func 

int 
int-exp 
int-var 
label 

lex 

line 
line-num 
lit 
log-exp 
map 
matrix 


name 


Meaning 
An angle in radians or degrees 


An array; syntax rules specify whether the bounds or dimen- 
sions can be specified 


An I/O channel associated with a file 
Specific to a COMMON block 


Conditional expression; indicates that an expression can be 
either logical or relational 


A constant value 

A data type keyword 

Specific to a DEF function 

An expression 

A file specification 

Specific to a FUNCTION subprogram 

An integer value 

An expression that represents an integer value 
A variable that contains an integer value 

An alphanumeric statement label 

Lexical; used to indicate a component of a compiler directive 
A statement line; may or may not be numbered 
A statement line number 

A literal value, in quotation marks 

Logical expression 

Specific to a MAP statement 

A two-dimensional array 


A name or identifier; indicates the declaration of a name 
or the name of a VAX BASIC structure, such as a SUB 
subprogram 


Mnemonic 


num 
param-list 
pass-mech 
real 
rel-exp 

str 

str-exp 
str-var 
sub 


target 


unsubs-var 


var 


Meaning 


A numeric value 

A parameter list, such as for a SUB subprogram 
A valid VAX BASIC passing mechanism 

A floating-point value 

Relational expression 

A character string 

An expression that represents a character string 
A variable that contains a character string 
Specific to a SUB subprogram 


The target point of a branch statement; either a line number 
or a label 


Unsubscripted variable, as opposed to an array element 


A variable 
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Summary of Technical Changes 


Summary of New and Changed Features for Version 3.3 


Version 3.3 of VAX BASIC includes support for the CDD/Plus Version 
4.0 CDO-format dictionaries while continuing to provide full support for 
the DMU-format dictionaries associated with previous versions of the 
CDD. Both types of dictionaries can coexist on a system and a program 
can access data definitions in both formats. This new functionality is 
implemented as follows: 


e §©Addition of the /DEPENDENCY_DATA qualifier to the DCL com- 
mand, BASIC 
e Addition of the lexical directive, %REPORT %DEPENDENCY 


e Modification of the lexical directive, %INCLUDE %FROM %CDD 


Descending keys are now supported on both primary and alternate 
keys. This new functionality is implemented by allowing the choice of 
ASCENDING or DESCENDING on key definition clauses in the OPEN 
statement. 


In addition, this documentation update contains numerous corrections and 
clarifications to previous documentation; these documentation changes do 
not reflect new features. 
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Summary of New and Changed Features for Version 3.0 


xxii 


Version 3.0 of VAX BASIC includes extensive graphics capabilities, struc- 
tured error handling techniques, enhancements to file I/O and other new 
features. All of these features are documented in this manual and the VAX 
BASIC User Manual except for the graphics features, which are documented 
in Programming with VAX BASIC Graphics. This section summarizes all of 
the major changes for this release. 


Graphics Capabilities 


VAX BASIC supports extensive graphics capabilities based on VAX GKS. 
The new graphics capabilities are available to you if you have the full or 
run-time VAX GKS kit installed on your system (Version 2.0 or later) and 
if you use supported graphics hardware. The main features of VAX BASIC 
graphics are as follows: 

e A short learning period 

e Convenient default values for attributes 

e Statements consisting of English words in simple constructs 

e Window and viewport settings that are easy to alter 


¢ Graphics subprograms that can be invoked with a variety of transfor- 
mation functions 


e Input statements for interactive graphics programs 
e Programs that can run on multiple devices 
e Programs that run on any hardware supported by VAX GKS 


Structured Error Handling 


VAX BASIC supports structured error handling with WHEN ERROR 
constructs. When an error occurs during execution of statements in a 
protected block of code, the error is handled by the associated attached or 
detached handler. The following new statements and functions enhance 
error-handling capabilities: 


e WHEN ERROR 

e RETRY 

e CONTINUE 

e HANDLER, EXIT HANDLER, and END HANDLER 
¢ OPTION HANDLE 

e CAUSE ERROR 


° RMSSTATUS and VMSSTATUS 


Although the new WHEN ERROR constructs are the preferred method 
for error handling, ON ERROR statements are supported for compatibility 
with previous versions of BASIC. 


Optional Line Numbers 


Line numbers are no longer required in VAX BASIC programs. A VAX 
BASIC program can have no line numbers at all, or it can use the tradi- 
tional line numbered statements; both are valid. A program with a line 
number on the first nonblank line is treated as a line-numbered program 
by the compiler. In the BASIC environment, programs with no line num- 
bers must be created with a text editor or copied into the environment 
with the OLD command. 


Array Bounds 


You can now specify the lower bound for any or all dimensions of non- 
virtual arrays. Previously, VAX BASIC arrays could only be zero-based. 
In addition, two new functions, LROUND and UBOUND, allow you to 
retrieve the lower and upper bounds of array dimensions. 


Improvements for Procedure Invocations 


This version of VAX BASIC includes additional flexibility for procedure 
invocations: 


e If an external function is called as a procedure, VAX BASIC performs 
parameter validation exactly as if the declared function had been 
invoked as a function. 


e The new keywords ANY and OPTIONAL ease parameter passing to 
non-BASIC routines. 


e Additional functionality has been added to the LOC function so that 
the address of an external function can be accessed. 


PRINT USING Format Strings 


Constant PRINT USING format strings are precompiled at compile time. 
Significant run-time performance gains can be achieved by recompiling 
programs that use constant format strings. 
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Single Keystroke Input 


The new function INKEY$ allows you to detect a single keystroke typed at 
a terminal. Function and keypad keys return a descriptive text string, for 
example, “F17’, and control characters return a single ASCII code. 


1/O Enhancements 


The following features have been added to enhance I/O capabilities: 


STREAM files are accessible with the OPEN statement. 


A WAIT clause can be added to the GET and FIND statements. This 
clause instructs VAX BASIC to wait on locked records rather than 
immediately returning the error RECBUCLOC (ERR = 154). 


The new keywords NX (next) and NXEQ (next or equal to) are syn- 
onyms for GT and GE respectively. These keywords make the GET 
and FIND statements more meaningful if an indexed file is accessed 
with descending keys. 


Miscellaneous Features 


The new PROGRAM statement allows you to optionally name a main 
program unit. This name becomes the module name of the compiled 
source. 


You can return a procedure value or the status of an image upon 
exiting with the following statements: 


— END/EXIT PROGRAM 
— END/EXIT FUNCTION 
— END/EXIT DEF 


By default, VAX BASIC calls VAX EDT from the environment. The 
user or the system manager can select callable VAX EDT, the VAX 
Text Processing Utility (VAXTPU), or the VAX Language Sensitive 
Editor as the default editor. Start-up time for editing files within 
the environment is shorter as it is no longer necessary to spawn a 
subprocess to access editors that are callable. 


System managers can prevent users escaping to DCL level from the 
environment by setting the user’s subprocess limit (PRCLM) to zero. 
A subprocess limit of 1 was previously required so that a user could 
use an editor within the environment. 


New extensions to the OPTION statement include the following: 
— OPTION ANGLE = degrees-or-radians 
— OPTION HANDLE = severity-level 


— OPTION CONSTANT TYPE = data-type 
— OPTION OLD VERSION = CDD 


The MID$ function can now be on the left side of an assignment 
statement. This feature allows partial string replacement. 


VAX BASIC statements, compiler directives, labels, and comment lines 
can now Start in column 1. 


You can include files from a text library with the %INCLUDE direc- 
tive. 

The suffixes $ (for strings) and % (for integers) are allowed on explic- 
itly declared variables and constants. 

Extensions to the REMAP and MAP DYNAMIC statements allow you 


to redefine the storage allocated to a previously declared static string 
variable. 


New functions MAX and MIN are provided for the comparison of a 
series of arguments. 


The new MOD function divides one numeric argument by another 
and returns the remainder. . 


The new compiler directive %PRINT allows you to print a message 
during the compilation of a source program without aborting the 
compilation. 


The new lexical directive %DECLARED allows you to determine 
whether or not a lexical variable has been declared. 
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Chapter 1 


Program Elements and Structure 


The building blocks of a VAX BASIC program are as follows: 


Program lines and their components 
The VAX BASIC character set 

VAX BASIC data types 

Variables and constants 

Expressions 

Program documentation 


These building blocks are described in the following sections. 


1.1 Components of Program Lines 


A VAX BASIC program is a series of program lines that contain instruc- 
tions for the VAX BASIC compiler. These instructions are in the form of 
statements that contain keywords, operators, and operands. 


All VAX BASIC program lines can contain the following: 


Statements 

Line numbers or labels 

Compiler directives 

Comment fields 

A line terminator (carriage return) 
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Only a line terminator is required in a program line. The other elements 
are optional. 


1.1.1 Line Numbers 


Line numbers are no longer required in VAX BASIC programs; you can 
compile, link, and execute a program with or without line numbers. There 
are, however, different rules for writing programs with line numbers 

and for writing programs without line numbers. These differences are 
described in the following sections. 


1.1.1.1 Programs With Line Numbers 


If you are entering program lines directly into the BASIC environment in 
line mode, then only those statements with line numbers are allowed to 

start in the first column. Also, any programs entered in line mode must 

have an initial line number associated with the first program line. 


A VAX BASIC line number must be a unique integer from 1 through 
32767, and must be terminated by a space or tab. VAX BASIC ignores 
leading spaces, tabs, and zeros in line numbers. Embedded spaces, tabs, 
and commas cause VAX BASIC to signal an error. 


In line mode, a line number followed by a carriage return does not 
constitute a VAX BASIC program line. A program line entered in line 
mode must contain a statement or a comment field. (Comment fields 
are discussed in Section 1.7.1). A new line number or a carriage return 
terminates a VAX BASIC program line. 


A program line can contain any number of text lines; however, a text line 
cannot exceed 255 characters. 


1.1.1.2 Programs Without Line Numbers 


VAX BASIC searches for a line number on the first line of program text 
when you 


e Load a program into the BASIC environment with the OLD command 
e Edit a program in the BASIC environment 


If no line number is found, then the following rules apply: 


¢ No line numbers are allowed in that program module. 
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e References to the ERL function and a RESUME statement to a line 
number are not allowed. 


e A subroutine will signal the same errors as it would if it were compiled 
with the /NOLINES qualifier. If an error is resignaled back to the 
caller, ERL gives the line number of the calling site, rather than the 
line number of the actual error in the subprogram. 


e The REM statement is not allowed. 


If your program contains multiple units, the point at which VAX BASIC 
breaks each program unit is determined by the placement of the statement 
that terminates each program unit. Any text that follows the program 
terminator becomes associated with the following program unit. A pro- 
gram terminator can be any END statement, such as an END PROGRAM 
statement followed by any valid expression. 


You cannot use the APPEND command in the BASIC environment, or a 
plus sign (+) at DCL level, to concatenate programs without line numbers. 


Note that when you compile a program from DCL, or when you copy a 
program into the BASIC environment with the OLD command, program 
statements can begin in the first column. 


Instead of line numbers, you can use labels to identify and reference 
program lines. 


1.1.2 Labels 


A label is a 1- to 31-character name that identifies a statement or block 
of statements. The label name must begin with a letter; the remaining 

characters, if any, can be any combination of letters, digits, dollar signs 
($), underscores (_), or periods (.). If the program is being entered in 
line mode, and therefore contains line numbers, then only line numbers 
and immediate mode statements can begin in the first character position. 


A label name must be separated from the statement it identifies with a 
colon (:). For example: 


Yes_routine: PRINT "Your answer is YES." 


The colon is not part of the label name. It informs VAX BASIC that the 
label is being defined rather than referenced. Consequently, the colon is 
not allowed when you use a label to reference a statement. For example: 


200 GOTO Yes_routine 
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You can reference a label almost anywhere you can reference a line 
number. However, there are the following exceptions: 


You cannot compare a label with the value returned by the ERL 
function. 


You cannot reference a label in an IF...THEN...ELSE statement without 
using the keyword GOTO or GO TO. You can use the implied GOTO 
form only to reference a line number. In the following example, the 
GOTO keyword is not required in statement 100 because the reference 
is to a line number. Because statement 200 references labels, the 
GOTO keyword is required. 


Example 


100 IF A% = BY 
THEN 1000 
ELSE 1050 


200 IF A$ = "YES" 
THEN GOTO Yes 
ELSE GOTO No 


1.1.3 Statements 


A VAX BASIC statement consists of a statement keyword and optional 
operators and operands. For example, both of these statements are valid: 


LET A% = 534% + (SUM% - DIF%) 
PRINT A% 


VAX BASIC statements can be either executable or nonexecutable: 


Executable statements perform operations (for example, PRINT, 
GOTO, and READ). 


Nonexecutable statements describe the characteristics and arrangement 
of data, specify usage information, and serve as comments in the 
source program (for example, DATA, DECLARE, and REM). 


VAX BASIC can accept and process one statement on a line of text, several 
statements on a line of text, multiple statements on multiple lines of text, 
and single statements continued over several lines of text. Each line of 
program text is associated with the last specified line number, and each 
must contain a keyword. 
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1.1.3.1 


Keywords 


Every VAX BASIC statement except LET and empty statements must begin 
with a keyword. A keyword is a reserved element of the VAX BASIC 
language. Keywords are used to 


e Define data and user identifiers 


e Perform operations 
e Invoke built-in functions 


NOTE 


Keywords are reserved words and cannot be used as user 
identifiers, such as variable names, labels, or names for MAP or 
COMMON areas. 


Keywords cannot be used in any context other than as VAX BASIC 
keywords. The assignment STRING$ = “YES”, for example, is invalid 
because STRING$ is a reserved VAX BASIC keyword and therefore cannot 
be used as a variable. Appendix D in this manual contains a list of the 
VAX BASIC keywords. 


A VAX BASIC keyword cannot have embedded spaces and cannot be split 
across lines of text. There must be a space, tab, or special character such 
as a comma between the keyword and any other variable or operator. 


Some keywords use two words. In this case, their spacing requirements 
vary, as shown in Table 1-1. 


Table 1-1: Keyword Space Requirements 


Optional 

Space Required Space No Space 

GO TO BY DESC FNEND 

GO SUB BY REF FNEXIT 

ON ERROR BY VALUE FUNCTIONEND 
END DEF FUNCTIONEXIT 
END FUNCTION NOECHO 
END GROUP NOMARGIN 
END IF SUBEND 
END PROGRAM SUBEXIT 
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Table 1-1 (Cont.): Keyword Space Requirements 
Optional 
Space Required Space No Space 
END RECORD 
END SELECT 
END SUB 
EXIT DEF 
EXIT FUNCTION 
EXIT SUB 
INPUT LINE 
MAP DYNAMIC 
MAT INPUT 
MAT LINPUT 
MAT PRINT 
MAT READ 


Identifying Program Units 


You can delimit a main program compilation unit with the PROGRAM 
and END PROGRAM statements. This allows you to identify a program 
with a name other than the file name. The PROGRAM name must not be 
the same as that of any SUB, FUNCTION, or PICTURE subprogram. 


Example 
PROGRAM Sort_out 


END PROGRAM 


If you include the PROGRAM statement in your program, the name you 
specify becomes the module name of the compiled source. This feature is 
useful when you use object libraries, because the librarian stores modules 
by their module names rather than by their file names. Similarly, module 
names are used by the VAX/VMS Debugger and the VAX/VMS Linker. 


For more information about program units, see the VAX BASIC User 
Manual. 
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1.1.3.3 Single-Statement Lines and Continued Statements 


A single-statement line consists of one statement on one numbered line, 
or one statement continued over two or more text lines. For example: 


30 PRINT B * C / 12 


This single-statement line has a line number, the keyword (PRINT), the 
operators (*, /), and the operands (B, C, 12). 


You can have a single statement span several text lines by typing an 
ampersand (&) and the RETURN key. Note that only spaces or tabs are 
valid between the ampersand and the carriage return. For example: 


OPEN "SAMPLE.DAT" AS FILE 2%, &[RET| 


SEQUENTIAL VARIABLE, &{RET| 
MAP ABC 


The ampersand continuation character may be used but is not required for 
continued REM statements. The following example is valid: 


REM This is a remark 
And this is also a remark 


You can continue any VAX BASIC statement, but you cannot continue a 
string literal or VAX BASIC keyword. The following example generates 
the error message “Unterminated string literal’. 


PRINT "IF-THEN-ELSE- & 
END-IF" 


This example is valid: 


PRINT “IF-"; & 
"THEN"; & 
"ELSE-"; & 
"END-"; & 
"Tru 


A more efficient way to continue string literals is to use the string concate- 
nation operator (+): 


PRINT "IF-" 
+ "THEN-" 
+ "ELSE-" 
+ “END-" 
+ "TF 


& & & & 
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VAX BASIC concatenates the four string literals at compilation and stores 
them as one string. When the PRINT statement executes, VAX BASIC 
displays the one concatenated string literal rather than four separate 
string literals, thereby causing your program to execute faster and more 
efficiently. 


1.1.3.4 Multi-Statement Lines 


Multi-statement lines contain several statements on one line of text or 
multiple statements on separate lines of text. All the statements on a 
multi-statement line are associated with a single line of code. 


Multiple statements on one line of text must be separated by backslashes 
(\). For example: 


40 PRINT A \ PRINT V \ PRINT G 


Because all statements are on the same program line, any reference to line 
number 40 refers to all three statements and execution begins with the 
first statement on the line. For example, VAX BASIC cannot execute the 
second statement without executing the first statement. 


You can also write a multi-statement program line that associates all 
statements with a single line number by placing each statement on a 
separate line. VAX BASIC assumes that such an unnumbered line of text 
is either a new statement or an IF statement clause. 


In the following example, each line of text begins with a VAX BASIC 
statement and each statement is associated with line number 400. 
Example 
400 PRINT A 

PRINT B 

PRINT "FINISHED" 


VAX BASIC also recognizes IF statement keywords on a new line of text 
and associates such keywords with the preceding IF statement. 
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Example 


100 REM Determine if the user's response 
was YES or NO. 
200 IF (A$ = "YES") OR (A$ = "Y") 
THEN PRINT "You typed YES" 
ELSE PRINT "You typed NO" 
STOP 
END IF 


The VAX BASIC compiler assigns listing line numbers to the statements as 
they occur physically in the program. 


Example 


1 100 REM Determine if the user's response 
2 was YES or NO. 

3 200 IF (A$ = "YES") OR (A$ = "Y") 

4 THEN PRINT "You typed YES" 

5 ELSE PRINT "You typed NO" 

6 STOP 

END IF 


“ 


You cannot use listing line numbers as targets of branch statements. The 
target of a branch statement such as GOTO must be a line number or a 
label. See the VAX BASIC User Manual for more information on listing file 
formats. 


You can use any VAX BASIC statement in a multi-statement line. Since 
the VAX BASIC compiler ignores all text following a REM keyword until 
it reaches a new line number, a REM statement must be the last statement 
on a multi-statement line. REM statements are disallowed in programs 
without line numbers. 


In the environment, a leading space or tab not followed by a line number 
implies a new statement in a multi-statement line, compiler commands 
and immediate mode statements cannot be preceded by a space, tab, 

or line number. If you enter a compiler command or immediate mode 
statement, you cannot add more continuation lines to the last program 
line. If you attempt to do so, VAX BASIC signals the error “Unknown 
command input.” 
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1.1.4 Compiler Directives 


Compiler directives are instructions for the VAX BASIC compiler. These 
instructions cause the VAX BASIC compiler to perform certain operations 
as it compiles the program. 


By including compiler directives in a program, you can: 


Place program titles and subtitles in the header that appears on each 
page of the listing file 


Place a program version identification string in both the listing file and 
object module 


Start or stop the inclusion of listing information for selected parts of a 
program 


Start or stop the inclusion of cross reference information for selected 
parts of a program 


Include VAX BASIC code from another source file or a text library 
Conditionally compile parts of a program 

Terminate compilation 

Include CDD record definitions in a VAX BASIC program 

Display messages during the compilation 


Follow these rules when using compiler directives: 


Compiler directives must begin with a percent sign 


Compiler directives must be the only text on the line (except for 
%IF-%THEN-%ELSE-%END-%IF) 


Compiler directives cannot appear within a quoted string 
Compiler directives can be preceded by an optional line number 


See the VAX BASIC User Manual and Chapter 3 in this manual for more 
information on compiler directives. 
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1.1.5 Line Terminators 


In the BASIC environment, a program line ends with a carriage return/line 
feed combination (the RETURN key) followed by an optional space or tab 
or a new line number. An ampersand followed by a carriage return ends a 
line of text, but not the program line. Note that spaces and tabs are valid 
between the ampersand and the carriage return; no other characters are 
valid. When line numbers are present, all statements between the first 
line number and the next line number are associated with the first line 
number. 


1.1.6 Lexical Order 


Lexical order refers to the order in which the statements in a program 
are compiled. In general terms, VAX BASIC compiles program lines in 
sequential order: multiple statements on a line of text are processed from 
left to right, and lines of text are processed from top to bottom. Note 
that certain VAX BASIC statements can alter this flow of compilation, for 
example GOSUB and GOTO. 


Some VAX BASIC statements, such as comments and MAP declarations, 
are nonexecutable. If program control passes to a nonexecutable state- 
ment, the VAX BASIC compiler executes the first statement that lexically 
follows the nonexecutable statement. 


1.2 VAX BASIC Character Set 


VAX BASIC uses the full ASCII character set. This includes 


e¢ The letters A through Z, both upper- and lowercase 
e = The digits 0 through 9 
¢ Special characters 


Appendix C in this manual lists the full ASCII character set and character 
values. 


The VAX BASIC compiler does not distinguish between upper- and 
lowercase letters except in string literals or within a DATA statement. The 
VAX BASIC compiler does not process characters in REM statements or 
comment fields, nor does it process nonprinting characters unless they are 
part of a string literal. 
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In string literals, VAX BASIC processes: 


e Lowercase letters as lowercase 
e¢ Nonprinting characters 


The ASCII character NUL (ASCII code 0) and line terminators cannot 
appear in a string literal. Use the CHR$ function or explicit literal notation 
to use these characters and terminators. 


You can use nonprinting characters in your program, for example, in string 
constants, but to do so you must use one of the following: 

e¢ A predefined constant such as ESC or DEL 

e The CHR$ function to specify an ASCII value 

e Explicit literal notation 


See Section 1.5.4 for more information on explicit literal notation. 


1.3 VAX BASIC Data Types 


Each unit of data in a VAX BASIC program has a specific data type that 
determines how that unit of data is to be interpreted and manipulated 
by the VAX BASIC compiler. This data type also determines how many 
storage bits make up the unit of data. 


VAX BASIC recognizes five primary data types: 


e Integer 

e Floating-point 

e Character string 

e Packed decimal 

e ~=Record’s file address 


Integer data is stored as binary values in a byte, word, or longword. These 
values correspond to the VAX BASIC data type keywords BYTE, WORD, 
and LONG; these are all subtypes of the type INTEGER. 


Floating-point values are stored using a signed exponent and a binary 
fraction. VAX BASIC allows four floating-point formats: single, double, 
G_floating, and H_floating. These formats correspond to the VAX BASIC 
data type keywords SINGLE, DOUBLE, GFLOAT, AND HFLOAT; these 
are all subtypes of the type REAL. 
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VAX BASIC packed decimal data is stored in a string of bytes. Refer to 
Chapter 19 of the VAX BASIC User Manual for more information on the 
storage of packed decimal data. 


Character data consists of strings of bytes containing ASCII code as binary 
data. The first character in the string is stored in the first byte, the second 
character is stored in the second byte, and so on. VAX BASIC allows up 
to 65535 characters for a STRING data element. 


In addition to this data type, VAX BASIC also recognizes a special RFA 
data type to provide information about a record's file address. An RFA 
uniquely specifies a record in a file: you can access RMS files of any 
organization by record’s file address. By specifying the disk address of 

a record, RMS retrieves the record at that address. Accessing records by 
RFA is more efficient and faster than other forms of random record access. 
The RFA data type can only be used for 


e RFA operations (the GETRFA function and the GET and FIND 
statements) 
e Assignments to other variables of the RFA data type 


¢ Comparisons with other variables of the RFA data type with the equal 
to (=) and not equal to ( <> _ ) relational operators 
e Formal and actual parameters 


e DEF and function results 


You cannot declare a constant of the RFA data type, nor can you use RFA 
variables for any arithmetic operations. 


The RFA data type requires 6 bytes of information. See the VAX BASIC 
User Manual for more information on Record File Addresses and the RFA 
data type. 


For the DECIMAL(d;s) data type, you can specify the total number of 
digits (d) in the data type and the number of digits to the right of the 
decimal point (s). For instance, DECIMAL(10,3) specifies decimal data 
with a total of 10 digits, 3 of which are to the right of the decimal point. 


Table 1-2 lists VAX BASIC data type keywords and summarizes 
VAX BASIC data types. 


July 1988 Program Elements and Structure 1-13 


Table 1-2: VAX BASIC Data Types 


Data Type 
Keyword 


Integer 
BYTE 
WORD 
LONG 


Real 
SINGLE 
DOUBLE 
GFLOAT 
HFLOAT 


Decimal 
DECIMAL(d;s) 


String 
STRING 


RFA 
RFA 


Size 


8 bits 
16 bits 
32 bits 


32 bits 
64 bits 
64 bits 


128 bits 


0 to 16 
bytes _ 


One 
character 
per byte 


6 bytes 


Range 


7128 to +127 


-32768 to +32767 


-2147483648 to 
+2147483647 


29 * 1078 to 
1.7 « 10°8 


29 * 10788 to 
1.7 * 10°8 


56 * 10778 to 
90 * 10°°8 


84 * 107*°* to 
59 * 104? 


1* 1077! to 1 * 
10°" 


Max = 65535 


NA 


Precision 
(decimal) 
(digits) 


NA 
NA 
NA 


16 


15 


33 


NA 


NA 


NA 


In Table 1-2, REAL and INTEGER are generic data type keywords that 
specify floating-point and integer storage, respectively. If you use the 
REAL or INTEGER keywords to type data, the actual data type (SINGLE, 
DOUBLE, GFLOAT, HFLOAT, BYTE, WORD, or LONG) depends on the 
current default. If you do not explicitly type one of the appropriate 
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subtypes, VAX BASIC uses the current subtype defaults for REAL and 
INTEGER. 


You can specify data type defaults in the BASIC environment with the SET 
and COMPILE commands, or from DCL level with the DCL command 
BASIC. You can also specify whether program values are to be typed 
implicitly or explicitly. The following sections discuss data type defaults 
and implicit and explicit data typing. 


1.3.1 Implicit Data Typing 


You can implicitly assign a data format to program values by adding a 
suffix to the variable name or constant value. If you do not specify any 
suffix, the variable or constant is assigned the current default data type. 
The following rules apply for implicit data typing: 

e A dollar sign suffix ($) specifies STRING storage. 

e A percent sign suffix (%) specifies INTEGER storage. 


e No special suffix character specifies storage of the default type, which 
can be INTEGER, REAL, or DECIMAL. 


With implicit data typing, the range and precision for program values are 
determined by the corresponding default data sizes or subtypes: 

e BYTE, WORD, or LONG for INTEGER values 

e SINGLE, DOUBLE, GFLOAT, or HFLOAT for REAL values 

e ©The default (d,s) values for DECIMAL values 


The default data type is determined by one of the following: 


e The system default (REAL) 


e The data type set for the BASIC environment with the SET or 
COMPILE compiler command 

e The data type set for the BASIC environment with the BASIC state- 
ment OPTION 


e The data type set for VAX BASIC with a qualifier for the DCL com- 
mand BASIC 


The VAX BASIC qualifiers for the SET and COMPILE commands are de- 


scribed in Chapter 2 of this manual. The qualifiers for the DCL command 
BASIC are listed in the VAX BASIC User Manual. 
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Note that if you compile your program with the /TYPE_DEFAULT= 
EXPLICIT qualifier (on either the DCL command BASIC or VAX BASIC 
command COMPILE), you can still add the appropriate suffixes to your 
variable names or constant values. The suffixes are useful because they 
identify the data type of the variable or constant immediately; the reader 
does not have to refer to the declarations at the top of the program to see 
which data type applies to a particular program value. However, with 
the /TYPE_DEFAULT=EXPLICIT qualifier, you must still explicitly assign 
data types to all program values or VAX BASIC signals an error. 


It is considered good programming practice to use explicit data typing 
because implicit data typing is dependent on compilation defaults. These 
defaults may change, thereby affecting the precision of the program 
values. 


1.3.2 Explicit Data Typing 


Explicit data typing means that you use a declarative statement to spec- 
ify the type, range, and precision of your program values. Declarative 
statements associate attributes such as data type and value with user 
identifiers. 


In the following example, the first DECLARE statement associates the 
constant value 03060 and the STRING data type with a constant named 
zip_code. The second DECLARE statement associates the STRING data 
type with emp_name, the DOUBLE data type with with_tax, and the 
SINGLE data type with int_rate. No constant values are associated with 
identifiers in the second DECLARE statement because they are variable 
names. 


Example 


DECLARE STRING CONSTANT zip_code = "03060" 
DECLARE STRING emp_name, DOUBLE with_tax, SINGLE int_rate 


With explicit data typing, each program variable within a program can 
have a different range and precision. You can explicitly assign data 
types to variables, constants, arrays, parameters, and functions; therefore, 
integer data does not have to take the compilation default types. Explicit 
data typing gives you more control over your program. 


Using the REAL and INTEGER keywords to explicitly type program 
values allows you to write programs that are transportable across systems, 
because these data type keywords specify that all floating-point and 
integer data take the current defaults for REAL and INTEGER. The data 
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type INTEGER, for example, specifies only that the constant or variable 

is an integer. The actual subtype (BYTE, WORD, or LONG) depends on 
the default set with the COMPILE or SET command, the DCL command 
BASIC, or with the OPTION statement. 


You can also specify a particular data type size for values declared 
INTEGER or REAL with compilation qualifiers. The /DOUBLE quali- 
fier, for instance, specifies that all data typed REAL is to be treated as 
double-precision data. 


The /TYPE_DEFAULT=EXPLICIT qualifier or OPTION TYPE=EXPLICIT 
statement allows you to specify that all program data must be explicitly 
typed. Compiling a program with /TYPE_DEFAULT= EXPLICIT or 
specifying OPTION TYPE=EXPLICIT means that any program value not 
explicitly declared causes VAX BASIC to signal an error. 


For new applications, DIGITAL recommends using VAX BASIC’s ex- 
plicit data typing features. See the VAX BASIC User Manual for more 
information. 


1.4 Variables 


A variable is a named quantity whose value can change during program 
execution. Each variable name refers to a location in the program’s storage 
area. Each location can hold only one value at a time. Variables of all 
data types can have subscripts that indicate their position in an array. You 
can declare variables implicitly or explicitly. 


Depending on the program operations specified, the value of a variable 
can change from statement to statement. VAX BASIC uses the most 
recently assigned value when performing calculations. This value remains 
in effect until a new value is assigned to the variable. 


VAX BASIC accepts these general types of variables: 
e Floating-point 


e Integer 

e = String 

e RFA 

e Packed decimal 
e §=Record 
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See the VAX BASIC User Manual for more information on RFA variables 
and RECORD data structures. 


1.4.1 Variable Names 


The name given to a variable depends on whether the variable is internal 
or external to the program and whether the variable is implicitly or 
explicitly declared. 


All variable names must conform to the following rules: 


The name can have from 1 to 31 characters. 
The name has no embedded spaces. 


The first character of the name must be an upper- or lowercase 
alphabetic character (A through Z). 


The last character of the name can be either a dollar sign ($) to 
indicate a string variable or a percent sign (%) to indicate an integer 
variable. If the last character is neither a dollar sign nor a percent 
sign, the name indicates a variable of the default type. 


The remaining characters, if present, can be any combination of upper- 
or lowercase letters (A through Z), numbers (0 through 9), dollar signs 
($), underscores (_), or periods (.). The use of underscores in 
variable names helps improve readability and is preferred to the use 
of periods. 


The name of an external, explicitly declared variable in VAX BASIC 
must follow the rules for naming any explicitly declared variable. 


Note that a program cannot have external, implicitly declared variables 
since all implicitly declared names except SUB subprogram names are 
internal to the program. 
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1.4.2 Implicitly Declared Variables 


VAX BASIC accepts three types of implicitly declared variables: 


e = Integer 
¢ String 
¢ Floating-point (or the default data type) 


The name of an implicitly declared variable defines its data type. Integer 
variables end with a percent sign (%), string variables end with a dollar 
sign ($), and variables of the default type (usually floating-point) end 
with any allowable character except a percent sign or dollar sign. All 
three types of variables must conform to the rules listed in Section 1.4.1 
for naming variables. The current data type default (INTEGER, REAL, or 
DECIMAL) determines the data type of implicitly declared variables that 
do not end in a percent sign or dollar sign. 


A floating-point variable is a named location that stores a single floating- 
point value. The current default size for floating-point numbers (SINGLE, 
DOUBLE, GFLOAT or HFLOAT) determines the data type of the floating- 
point variable. The following are valid floating-point variable names: 


C Li sio ID_NUMBER 
M1 BIG47 STORAGE—LOCATION—_FOR_XX 
F67T_J 72. STRESS_VALUE 


If a numeric value of a different data type is assigned to a floating-point 
variable, VAX BASIC converts the value to a floating-point number. 


An integer variable is a named location that stores a single integer value. 
The current default size for integers (BYTE, WORD, or LONG) determines 
the data type of an integer variable. The following are valid integer 
variable names: 

ABCDEFG% C_8% RECORD_NUMBER% 


B% D6E7%  THE—VALUE_I_-WANT% 


If the default data type is INTEGER, the percent suffix (%) is not 
necessary. 
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If you assign a floating-point or decimal value to an integer variable, VAX 
BASIC truncates the fractional portion of the value. It does not round to 
the nearest integer. For example: 


100 BY = -5.7 
VAX BASIC assigns the value -5 to the integer variable, not -6. 


A string variable is a named location that stores strings. The following are 
valid string variable names: 


C1$ M$ EMPLOYEE_NAME$ 
L_6$ F34G$ TARGET_RECORD$ 
ABC1$ T..$ STORAGE_SHELF_IDENTIFIER$ 


Strings have both value and length. VAX BASIC sets all string variables 
to a default length of zero before program execution begins, with the 
exception of those variables in a COMMON, MAP, virtual array, or record 
definition. See the COMMON statement and the MAP statement in 
Chapter 4 of this manual for information on string length in COMMON 
and MAP areas. See the VAX BASIC User Manual for information on 
default string length in virtual arrays. 


During execution, the length of a character string associated with a string 
variable can vary from zero (signifying a null or empty string) to 65535 
characters. 


1.4.3 Explicitly Declared Variables 


VAX BASIC lets you explicitly assign a data type to a variable or an array. 
For example: 


DECLARE DOUBLE Interest_rate 


Data type keywords are described in Section 1.1.3.1. For more information 
on explicit declaration of variables, see the sections on the COMMON, 
DECLARE, DIMENSION, DEF, FUNCTION, EXTERNAL, MAP, and SUB 
statements in Chapter 4 of this manual. See also the VAX BASIC User 
Manual. 
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1.4.4 Subscripted Variables and Arrays 


A subscripted variable references part of an array. Arrays can be of any 
valid data type. Subscripted variables and arrays follow the same naming 
conventions as unsubscripted variables. Subscripts follow the variable 
name in parentheses and define the variable’s position in the array. When 
you create an array, you specify the maximum size of the array (the 
bounds) in parentheses following the array name. 


In the following example, the DECLARE statement sets the bounds of the 
array emp_name to 1000. Therefore, the maximum value for an emp_name 
subscript is 1000. The bounds of the array define the maximum value for 
a subscript of that array. 


Example 


DECLARE STRING emp_name(1000) 
FOR I% = 0% TO 1000% 

INPUT "Employee name"; emp_name(I%) 
NEXT I% 


Subscripts can be any positive LONG integer value between 0 and 
2147483647. 


NOTE 


By default, VAX BASIC signals an error if a subscript is bigger 
than the allowable range. Note, however, that the amount of 
storage the system can allocate depends on available memory. 
Therefore, very large arrays may cause an internal allocation 
error even though the subscript is still within the specified 
range. 


An array is a set of data ordered in any number of dimensions. A one- 
dimensional array, like emp_name(1000), is called a list or vector. A 
two-dimensional array, like payroll _data(5,5), is called a matrix. An array 
of more than two dimensions, like big_array(15,9,2), is called a tensor. 


As a default, VAX BASIC arrays are always zero-based. The number of 
elements in any dimension includes element number zero. For example, 
the array emp_name contains 1001 elements, since VAX BASIC allocates 
element zero. Payroll_data(5,5) contains 36 elements because VAX BASIC 
allocates row and column zero. 


Program Elements and Structure 1-21 


Often, however, applications call for arrays that are not zero-based. In 
VAX BASIC, you can define arrays that are not zero-based by specifying a 
lower bound, as well as an upper bound, for the subscripts. In this way, 
you can create an array with arbitrary starting and ending points. For 
example, you might want to create array birth_rate that holds the annual 
birth rate statistics for the years 1950 through 1985: 


DECLARE birth_rate(1950 TO 1985) 


Lower bounds are not allowed with virtual arrays or arrays used in 
MAT statements. However, you can specify lower bounds for any or all 
dimensions of a compile-time dimensioned array. If a multi-dimensional 
array is declared with lower bounds specified for some dimensions and 
not others, zero will be used for those dimensions without lower bounds. 


You can use the UBOUND and LBOUND functions to determine the 
upper and lower bounds of an array. For a description of these funtions, 
see Chapter 4 of this manual. 


For all arrays except virtual arrays, the total number of array elements 
cannot exceed 2147483647. Note, however, that this is a theoretical value; 
the actual maximum size of an array which you can declare depends on 
the configuration of your system. 


VAX BASIC arrays can have up to 32 dimensions. You can specify the 
type of data the array contains with data type keywords. Table 1-2 lists 
VAX BASIC data types. 


An element in a one-dimensional array has a variable name followed by 
one subscript in parentheses. There can be a space between the array 
name and the subscripts. For example: 


A(6%) 

B (6%) 

C$ (6%) 

A(6%) refers to the seventh item in this list: 

A(O%) = AC1%) = =—A( 2%) AC 3%) (4%) (5%) A (6%) 


An element in a two-dimensional array has two subscripts, in parentheses, 
following the variable name. The first subscript specifies the row number 
and the second subscript specifies the column. Use a comma to separate 
the subscripts. You can include a space between the array name and the 
subscripts if you like. For example: 


A (7%,2%)  AL(4%,6%) = AS (10%,10%) 
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In the following figure, the arrow points to the element specified by the 
subscripted variable A%(4%,6%): 


COLUMNS 
0123456 
RO 0000000 
Oo1 0000000 
w2 0000000 
$3 0000000 
4 00000 00 a—— A%(4%,6%) 


ZK-5549-86 


An element in an array has as many subscripts as there are dimensions. 


Although a program can contain a variable and an array with the same 
name, this is poor programming practice. Variable A and the array 
A(3%,3%) are separate entities and are stored in completely separate 
locations, so it is a good idea to give them different names. 


Note that a program cannot contain two arrays with the same name but 
a different number of subscripts. For example, the arrays A(3%) and 
A(3%,3%) are invalid in the same program. 


VAX BASIC arrays can be redimensioned at run time. See the VAX BASIC 
User Manual for more information on arrays. 


1.4.5 Initialization of Variables 


VAX BASIC sets variables to zero or null values at the start of program 
execution. Variables initialized by VAX BASIC include: 


¢ Numeric variables and in-storage array elements (except those in MAP 
or COMMON statements). 


e String variables (except those in MAP or COMMON statements). 


e Variables in subprograms. Subprogram variables are initialized to zero 
or the null string each time the subprogram is called. 
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VAX BASIC does not initialize the following: 


¢ Virtual arrays 
e Variables in MAP and COMMON areas 


1.5 Constants 


A constant is a numeric or character literal that does not change during 
program execution. A constant can also be named and associated with a 
data type. VAX BASIC allows the following types of constants: 


e Numeric: 
— Floating-point 
— Integer 
— Packed decimal 
¢ String (ASCII characters enclosed in quotation marks) 


A constant of any of the above data types can be named with the 
DECLARE CONSTANT statement. You can then refer to the constant 
by name in your program. Refer to Section 1.5.3 for information on 
naming constants. 


You can use the OPTION statement to declare a default data type for all 
constants in your program. This statement allows you to specify a data 
type for only the constants in your program; you can specify a different 
data type for variables. You can also use a special numeric literal notation 
to specify the value and data type of a numeric literal. Numeric literal 
notation is discussed in Section 1.5.4. 


If you do not specify a data type for a numeric constant with the 
DECLARE CONSTANT statement or with numeric literal notation, 

the type and size of the constant is determined by the default REAL, 
INTEGER, or DECIMAL type set with the DCL command BASIC, the VAX 
BASIC SET or COMPILE commands, or the OPTION statement. 


To simplify the representation of certain ASCII characters and mathemati- 
cal values, VAX BASIC also supplies some predefined constants. 


The following sections discuss numeric and string constants, named 
constants, numeric literal notation, and predefined constants. 
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1.5.1 Numeric Constants 


A numeric constant is a literal or named constant whose value never 
changes. In VAX BASIC, a numeric constant can be a floating-point 
number, an integer, or a packed decimal number. The type and size of a 
numeric constant is determined by 


e The system default values 

e The defaults set by the qualifiers for the DCL command BASIC 
e The data type qualifiers specified with the COMPILE command 
e The defaults set by the SET command 


e¢ The data type specified in a DECLARE CONSTANT or OPTION 
statement 


e Numeric literal notation 


If you use a declarative statement to name and declare the data type of 
a numeric constant, the constant is of the type and size specified in the 
statement. For example: 


DECLARE BYTE CONSTANT age = 12 


This example associates the numeric literal 12 and the BYTE data type 
with the identifier age. To specify a data type for an unnamed numeric 
constant, you must use the numeric literal notation format described in 
Section 1.5.4. 


1.5.1.1 Floating-Point Constants 


A floating-point constant is a literal or named constant with one or more 
decimal digits, either positive or negative, with an optional decimal point 
and an optional exponent (E notation). If the default data type is integer, 
VAX BASIC will treat the literal as an INTEGER unless it contains a 
decimal point or the character E. If the default data type is DECIMAL, an 
E is required or VAX BASIC treats the literal as a packed decimal value. 


The following table contains examples of floating-point literals with REAL, 
INTEGER, and DECIMAL default data types. 
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REAL INTEGER DECIMAL 


-8.738 -8.738 -8.738 
239.21E-6 239.21E-6 239.21E-6 
Wie Wf, 79E 

299 299E 2995 


Very large and very small numbers can be represented in E (exponential) 
notation. If a positive number appears in E notation, it can be preceded 
by an optional plus sign (+). A negative number in E notation must be 
preceded by a minus sign (—). A number can be carried to a maximum 
of 6 decimal places for SINGLE precision, 16 decimal places for DOUBLE 
precision, 15 decimal places for GFLOAT precision, and 33 places for 
HFLOAT precision. 


To indicate E notation, a number must be followed by the letter E. It also 
must be followed by an exponent sign and an exponent. The exponent 
sign indicates if the exponent is either positive or negative and is optional 
only if you are specifying a positive exponent. The exponent is an integer 
constant (the power of 10). 


Table 1-3 compares numbers in standard and E notation. 


Table 1-3: Numbers in E Notation 


Standard Notation E Notation 
.0000001 .1E-06 
1,000,000 .1E+07 
-10,000,000 -. 1E+08 
100,000,000 .1E+09 
1,000,000,000,000 .1E+13 


The range and precision of floating-point constants are determined by the 
current default data types or the explicit data type used in the DECLARE 
CONSTANT statement. However, there are limits to the range allowed 
for numeric data types. Table 1-2 lists VAX BASIC data types and ranges. 
VAX BASIC signals the fatal error “Floating point error or overflow” 
(ERR=48) when your program attempts to specify a constant value outside 
of the allowable range for a floating-point data type. 
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1.5.1.2 


Integer Constants 


An integer constant is a literal or named constant, either positive or 
negative, with no fractional digits and an optional trailing percent sign 
(%). The percent sign is required for integer literals only if the default 
type is not INTEGER. 


In the following table, the values are all integer constants. The presence 
of the percent sign varies depending on the default data type. 


REAL or 
INTEGER DECIMAL 
81257 81257% 
-3477 -3477% 
79 79% 


The range of allowable values for integer constants is determined by 
either the current default data type or the explicit data type used in the 
DECLARE CONSTANT statement. Table 1-2 lists VAX BASIC data 
types and ranges. VAX BASIC signals an error for a number outside the 
applicable range. 


If you want VAX BASIC to treat numeric literals as integer numbers, you 
must do one of the following: 


e Set the default data type to INTEGER 
e Make sure the literal has a percent sign suffix 
°¢ Use explicit literal notation 


The VAX BASIC compiler must convert numeric literals when assigning 
them to integer variables. This means that your program runs somewhat 
slower than it would if integer values were explicitly declared. You can 
prevent this conversion step by using one of the following: 

e Percent signs for integer constants 

e Numeric literal notation 

e Named integer constants 


NOTE 


You cannot use percent signs in integer constants that appear in 
DATA statements. An attempt to do so causes VAX BASIC to 
signal “Data format error” (ERR=50). 
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1.5.1.3 Packed Decimal Constants 


A packed decimal constant is a number, either positive or negative, that 
has a specified number of digits and a specified decimal point position 
(scale). You specify the number of digits (d) and the position of the 
decimal point (s) when you declare the constant as a DECIMAL(d;s). If 
the constant is not declared, the number of digits and the position of the 
decimal is determined by the representation of the constant. 


For example, when the default data type is DECIMAL, 1.234 is a 
DECIMAL(4,3) constant, regardless of the default decimal size. Likewise, 
using numeric literal notation, "1.234"P is a DECIMAL(4,3) constant, 
regardless of the default data type and default DECIMAL size. Numeric 
literal notation is described in Section 1.5.4. 


1.5.2 String Constants 


String constants are either string literals or named constants. A string 
literal is a series of characters enclosed in string delimiters. Valid string 
delimiters are: 


¢ Double quotation marks ("text") 
¢ Single quotation marks (‘text’) 


You can embed double quotation marks within single quotation marks 
(‘this is a “text” string’) and vice versa (“this is a ‘text’ string”). Note, 
however, that VAX BASIC does not accept incorrectly paired quotation 
marks and that only the outer quotation marks must be paired. The 
following character strings, for example, are valid: 


"The record number does not exist." 

"I'm here!" 

"The terminating ‘condition' is equal to A$." 
"REPORT 543" 


The following strings are not valid: 


"Quotation marks that do not match' 
"No closing quotation mark 


Characters in string constants can be letters, numbers, spaces, tabs, 8- 
bit data characters, or the NUL character (ASCII code 0). If you need a 
string constant that contains a NUL, you should use the NUL predefined 
constant. See Section 1.5.4 in this manual for information on explicit 
literal notation. 
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The VAX BASIC compiler determines the value of the string constant by 
scanning all its characters. For example, because of the number of spaces 
between the delimiters and the characters, these two string constants are 
not the same: 


" END-OF-FILE REACHED " 
"END-OF-FILE REACHED" 


VAX BASIC stores every character between delimiters exactly as you type 
it into the source program, including: 


e Lowercase letters (a—z) 

e Leading, trailing, and embedded spaces 
e Tabs 

e Special characters 


The delimiting quotation marks are not printed when the program is 
executing. The value of the string constant does not include the delimiting 
quotation marks. 


Example 
PRINT "END-OF-FILE REACHED" 


END 


Output 
END-OF-FILE REACHED 


Note, however, that VAX BASIC prints double or single quotation marks 
when they are enclosed in a second paired set: 


Example 
PRINT ‘FAILURE CONDITION: "RECORD LENGTH"! 


END 


Output 
FAILURE CONDITION: "RECORD LENGTH" 
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1.5.3 Named Constants 


VAX BASIC allows you to name constants. You can assign a name to a 
constant that is either internal or external to your program and refer to the 
constant by name throughout the program. This naming feature is useful 
for the following reasons: 


e If acommonly used constant must be changed, you need to make only 
one change in your program. 


e A logically named constant makes your program easier to understand. 


You can use named constants anywhere you can use a constant, for 
example, to specify the number of elements in an array. 


You cannot change the value of an explicitly named constant during 
program execution. To change the value of a constant, you must change 
the program statement that names the constant and declares its value, and 
then recompile the program. 


1.5.3.1 Naming Constants Within a Program Unit 


You name constants within a program unit with the DECLARE statement. 


Example 


DECLARE DOUBLE CONSTANT preferred_rate = .147 
DECLARE SINGLE CONSTANT normal_rate = .162 
DECLARE DOUBLE CONSTANT risky_rate = .175 


new_bal = old_bal * (1 + preferred_rate)“years_payment 


When interest rates change, only three lines have to be changed rather 
than every line that contains an interest rate constant. 


Constant names must conform to the rules for naming internal, explicitly 
declared variables listed in Section 1.4.1. Note that constant names cannot 
have embedded spaces. 


The value associated with a named constant can be a compile-time 
expression as well as a literal value, as shown in the following example. 
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Example 


DECLARE STRING CONSTANT Congrats = & 
Ww eww nnn wwe e nnn n nee +" + LF + CR + & 
"| Congratulations! |" + CR + CR + & 
CP a a +t 


PRINT Congrats 


PRINT Congrats 


Named constants can save you programming time because you do not 
have to retype the value every time you want to display it. Named 
constants can save you execution time because the named constant is 
known at compilation time. 


Valid operators in DECLARE CONSTANT expressions include all valid 
arithmetic, relational, and logical operators except exponentiation. You 
cannot use built-in functions in DECLARE CONSTANT expressions. 


VAX BASIC allows constants of all data types except RFA to be named as 
expressions. Because you cannot declare a constant of the RFA data type 
you cannot name one as an expression. The following example illustrates 
the concept of naming constants as expressions: 


DECLARE DOUBLE CONSTANT & 
min_value = 0, & 
max_value = PI/2 


You can specify only one data type in a DECLARE CONSTANT statement. 
To declare a constant of a different data type, you must use a second 
DECLARE CONSTANT statement. 


1.5.3.2 Naming Constants External to a Program Unit 


To declare constants outside the program unit, use the EXTERNAL state- 
ment. 
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Example 


EXTERNAL LONG CONSTANT SS$_NORMAL 
EXTERNAL WORD CONSTANT IS_SUCCESS 


The first line declares the VAX/VMS status code SS$_NORMAL to be 
an external LONG constant. The second line declares IS_SUCCESS, a 
success code, to be an external WORD constant. Note that VAX BASIC 
allows only external BYTE, WORD, LONG, and SINGLE constants. 
The VAX/VMS Linker supplies the values for the constants specified in 
EXTERNAL statements. 


External constant names cannot exceed 31 characters and must conform to 
the rules for naming external variables listed in Section 1.4.1. No external 
constant name can have embedded spaces. In VAX BASIC, the named 
constant might be a system status code or a global constant declared in a 
VAX MACRO or VAX BLISS program. 


1.5.4 Explicit Literal Notation 


You can specify the value and data type of numeric literals by using a 
special notation called explicit literal notation. The format of this notation 
is as follows: 


{radix] "num-str-lit" [data-type] 
Radix specifies an optional base, which can be any of the following: 
Decimal (base 10) 
Binary (base 2) 
Octal (base 8) 


Hexadecimal (base 16) 
ASCII 


> x OVD 


The VAX BASIC default radix is decimal. Binary, octal, and hexadecimal 
notation allow you to set or clear individual bits in the representation of 
an integer. This feature is useful in forming conditional expressions and in 
using logical operations. The ASCII radix causes VAX BASIC to translate 
a single ASCII character to its decimal equivalent. This decimal equivalent 
is an INTEGER value; you specify whether the INTEGER subtype should 
be BYTE, WORD, or LONG. 
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Num-str-lit is a numeric string literal. It can be the digits 0 and 1 when 
the radix is binary, the digits 0 through 7 when the radix is octal, the 
digits 0 through F when the radix is hexadecimal, and the digits 0 through 
9 when the radix is decimal. When the radix is ASCII, num-str-lit can be 
any valid ASCII character. 


Data-type is an optional single letter that corresponds to a data type 
keyword, excluding INTEGER and REAL: 


BYTE 

WORD 
LONG 
SINGLE 
DOUBLE 
GFLOAT 
HFLOAT 
DECIMAL 

Cc CHARACTER 


som eo De wl a a 


Note that data-type for the ASCII radix is limited to BYTE, WORD, or 
LONG. For example: 


D"255"L Specifies a LONG decimal constant with a value of 255 
"4000"F Specifies a SINGLE decimal constant with a value of 4000 
—"125"B Specifies a BYTE decimal constant with a value of -125 
A"M"L Specifies a LONG integer constant with a value of 77 
A"m"B Specifies a BYTE integer constant with a value of 109 


A quoted numeric string alone, without a radix and a data type, is a string 
literal, not a numeric literal. For example: 


"255"W Specifies a WORD decimal constant with a value of 255 
"259" Is a string literal 
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If you specify a binary, octal, or hexadecimal radix, data-type must be an 
integer. If you do not specify a data type, VAX BASIC uses the default 
integer data type. For example: 

BY11111111"B Specifies a BYTE binary constant with a value of -1 


BY11111111"W Specifies a WORD binary constant with a value of 255 


BY11111111" Specifies a binary constant of the default data type (BYTE, 
WORD, or LONG) 

BY11111111"F Is illegal because F is not an integer data type 

X"FF"B Specifies a BYTE hexadecimal constant with a value of -1 

X"FFE"W Specifies a WORD hexadecimal constant with a value of 255 

XUFE’D Is illegal because D is not an integer data type 

0"377"B Specifies a BYTE octal constant with a value of -1 

0"377"W Specifies a WORD octal constant with a value of 255 

0"377"G Is illegal because G is not an integer data type 


When you specify a radix other than decimal, overflow checking is per- 
formed as if the numeric string were an unsigned integer. However, when 
this value is assigned to a variable or used in an expression, the VAX 
BASIC compiler treats it as a signed integer. 


In the following example, VAX BASIC sets all 8 bits in storage location 
A. Because A is a BYTE integer, it has only 8 bits of storage. Because the 
8-bit two’s complement of 1 is 11111111, its value is -1. If the data type 
were W (WORD), VAX BASIC would set the bits to 0000000011111111, 
and its value would be 255. 


Example 


DECLARE BYTE A 
A = B"11111111"B 
PRINT A 


Output 


“1 


NOTE 


In VAX BASIC, a D can appear in both the radix position and 
the data type position. D in the radix position specifies that 
the numeric string is to be treated as a decimal number (base 
10). D in the data type position specifies that the value is to 
be treated as a double-precision, floating-point constant. P in 
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the data type position specifies a packed decimal constant. For 
example: 


"255"D Specifies a double-precision constant with a value of 
255 


"255.55"P Specifies a DECIMAL constant with a value of 255.55 
You can use explicit literal notation to represent a single-character string 
in terms of its 8-bit ASCII value. For example: 
(radix] num-str-lit C 


The letter C is an abbreviation for CHARACTER. The value of the numeric 
string must be from 0 through 255. This feature lets you create your own 
compile-time string constants containing nonprinting characters. 


The following example declares a string constant named control_g (ASCII 
decimal value 7). When VAX BASIC executes the PRINT statement, the 
terminal bell sounds. 

Example 


DECLARE STRING CONSTANT control_g = "7"C 
PRINT control_g 


1.5.5 Predefined Constants 


Predefined constants are symbolic representations of either ASCII charac- 
ters or mathematical values. They are also called compile-time constants 
because their value is known at compilation rather than at run time. 


Predefined constants help you 
e Format program output to improve readability 


e Make source code easier to understand 


Table 1-4 lists the predefined constants supplied by VAX BASIC, their 
ASCII values, and their functions. 
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Table 1—4: Predefined Constants 


Constant 
BEL (Bell) 
BS (Backspace) 


HT (Horizontal Tab) 


LF (Line Feed) 
VT (Vertical Tab) 


FF (Form Feed) 
CR (Carriage Return) 


SO (Shift Out) 


SI (Shift In) 


ESC (Escape) 
SP (Space) 


DEL (Delete) 
PI 


Decimal 
ASCII Value 


7 
8 


10 
11 


12 


13 


14 


15 


27 


32 


127 


None 


Function 
Sounds the terminal bell 


Moves the cursor one position to 
the left 


Moves the cursor to the next 
horizontal tab stop 


Moves the cursor to the next line 


Moves the cursor to the next 
vertical tab stop 


Moves the cursor to the start of 
the next page 


Moves the cursor to the begin- 
ning of the current line 


Shifts out for communications 
networking, screen formatting, 
and alternate graphics 


Shifts in for communications 
networking, screen formatting, 
and alternate graphics 


Marks the beginning of an escape 
sequence 


Inserts one blank space in 
program output 


Deletes the last character entered 


Represents the number PI with 
the precision of the default 
floating-point data type 


You can use predefined constants in many ways. For instance, the fol- 
lowing example shows how to print and underline a word on a hard copy 


terminal. 
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Example 


PRINT "“NAME:" + BS + BS + BS + BS + BS + "_____ " 
END 


Output 
NAME: 


The following example shows how to print and underline a word on a 
VT100 video display terminal. 
Example 


PRINT ESC + "[4mNAME:" + ESC + "(Om" 
END 


Output 


NAME: 





Note that the “m” in the above example must be lowercase. 


You can also create your own predefined constants with the DECLARE 
CONSTANT statement. 


In the following example, the first DECLARE statement defines under- 
lined_name as a string constant. The second DECLARE statement defines 
D_PI as a DOUBLE constant equal to the predefined constant PI. If the de- 
fault REAL data size is SINGLE, the program can use both single-precision 
PI and double-precision D_PI. 


Example 


DECLARE STRING CONSTANT underlined_name = ESC + "[4mNAME:" + ESC + "(Om" 
DECLARE DOUBLE CONSTANT D_PI = PI 

PRINT underlined_name 

PRINT D_PI,,PI 


1.6 Expressions 


VAX BASIC expressions consist of operands (numbers, strings, constants, 
variables, functions, and array elements) separated by arithmetic, string, 
relational, and logical operators. 
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Almost all VAX BASIC expressions yield numeric values. The only 
exceptions are string concatenation expressions and invocations of string- 
valued functions. By using different combinations of numeric operators 
and operands, and by using the resulting values, you can produce 


¢ Numeric expressions 
e String expressions 
e¢ Conditional expressions 


VAX BASIC evaluates expressions according to operator precedence and 
uses the results in program execution. Parentheses can be used to group 
operands and operators, thus controlling the order of evaluation. 


The following sections explain the types of expressions you can create and 
the way VAX BASIC evaluates expressions. 


1.6.1 Numeric Expressions 


Numeric expressions consist of floating-point, integer, or packed decimal 
operands separated by arithmetic operators and optionally grouped by 
parentheses. Table 1-5 shows how numeric operators work in numeric 
expressions. 


Table 1-5: Arithmetic Operators 


Operator Example Use 

+ A+B Add B to A 

- A-B Subtract B from A 

* A*B Multiply A by B 

/ A/B Divide A by B 

: A’B Raise A to the power B 
* A**B Raise A to the power B 


In general, two arithmetic operators cannot occur consecutively in the 
same expression. Exceptions are the unary plus and unary minus. The 
following expressions are valid. 
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A* +B 

A-*-B 

A * (-B) 

A*+-+-8 

The following expression is not valid: 
A-+*B 


An operation on two numeric operands of the same data type yields a 
result of that type. For example: 


A% + B% Yields an integer value of the default type 
G3 * M5 Yields a floating-point value if the default type is REAL 


If the result of the operation exceeds the range of the data type, VAX 
BASIC signals an overflow error message. 


The following example causes VAX BASIC to signal the error “Integer 
error or overflow” because the sum of A and B (254) exceeds the range of 
-128 to +127 for BYTE integers. Similar overflow errors occur for REAL 
and DECIMAL data types whenever the result of a numeric operation is 
outside the range of the corresponding data type. 


Example 


DECLARE BYTE A, B 
A = 127 

B = 127 

PRINT A + B 

END 


It is possible to assign a value of one data type to a variable of a different 
data type. When this occurs, the data type of the variable overrides the 
data type of the assigned value. The following example assigns the value 
32 to the integer variable A% even though the floating-point value of the 
expression is 32.13. 


Example 


AZ = 5.1 * 6.3 
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1.6.1.1 Floating-Point and Integer Promotion Rules 


When an expression contains operands with different data types, the data 
type of the result is determined by VAX BASIC’s data type promotion 
rules: 


e With one exception, VAX BASIC promotes operands with different 
data types to the lowest common data type that can hold the largest 
or most precise possible value of either operand’s data type. VAX 
BASIC then performs the operation using that data type, and yields a 
result of that data type. 


e The exception is that when an operation involves SINGLE and LONG 
data types, VAX BASIC promotes the LONG data type to SINGLE 
rather than DOUBLE, performs the operation, and yields a result of 
the SINGLE data type. 


Note that VAX BASIC does sign extension when converting BYTE and 
WORD integers to a higher INTEGER data type (WORD or LONG). The 
high order bit (the sign bit) determines how the additional bits are set 
when the BYTE or WORD is converted to WORD or LONG. If the high 
order bit is zero (positive), all higher-order bits in the converted BYTE or 
WORD are set to zero. If the high order bit is 1 (negative), all higher-order 
bits in the converted BYTE or WORD are set to 1. 


Table 1-6 lists the data type results possible in numeric expressions that 
combine BYTE, WORD, LONG, SINGLE, and DOUBLE data. Table 1-7 
lists the data type results possible in numeric expressions that combine the 
data types GFLOAT and HFLOAT. When the operands are DOUBLE and 
GFLOAT, VAX BASIC promotes both values to HFLOAT, and returns an 
HFLOAT value. The promotion of DOUBLE and GFLOAT to HFLOAT is 
necessary because a DOUBLE value is more precise than a GFLOAT value, 
but cannot contain the largest possible GFLOAT value. Consequently, 
VAX BASIC promotes these data types to a data type that can hold the 
largest and most precise value of either operand. 
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Table 1-6: Result Data Types in VAX BASIC Expressions 






SINGLE 
LONG 


DOUBLE 
SINGLE 



















BYTE BYTE WORD DOUBLE 


WORD WORD WORD LONG SINGLE DOUBLE 
LONG LONG LONG LONG SINGLE DOUBLE 
SINGLE SINGLE SINGLE SINGLE SINGLE DOUBLE 
DOUBLE | DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE 








For example, if one operand is SINGLE and one operand is DOUBLE, VAX 
BASIC promotes the SINGLE value to DOUBLE, performs the specified 
operation, and returns the result as a DOUBLE value. This promotion 

is necessary because the SINGLE data type has less precision than the 
DOUBLE value, whereas the DOUBLE data type can represent all possible 
SINGLE values. If VAX BASIC did not promote the SINGLE value and the 
operation yielded a result outside of the SINGLE range, loss of precision 
and significance would occur. 


The data types BYTE, WORD, LONG, SINGLE, and DOUBLE form a 
simple hierarchy: if all operands in an expression are of these data types, 
the result of the expression is the highest data type used in the expression. 


Table 1-7: VAX BASIC Result Data Types 





GFLOAT 
GFLOAT 






HFLOAT 
HFLOAT 





BYTE 










WORD GFLOAT HFLOAT 
LONG GFLOAT HFLOAT 
SINGLE GFLOAT HFLOAT 
DOUBLE HFLOAT HFLOAT 
GFLOAT GFLOAT HFLOAT 


HFLOAT HFLOAT HFLOAT 
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1.6.1.2 DECIMAL Promotion Rules 


VAX BASIC allows the DECIMAL(d,s) data type. The number of digits 
(d) and the scale or position of the decimal point (s) in the result of 
DECIMAL operations depends on the data type of the other operand. If 
one operand is DECIMAL and the other is DECIMAL or INTEGER, the d 
and s values of the result are determined as follows: 


If both operands are typed DECIMAL, and if both operands have the 
same digit (d) and scale (s) values, no conversions occur and the 
result of the operation has exactly the same d and s values as the 
operands. Note, however, that overflow can occur if the result exceeds 
the range specified by the d value. 


If both operands are DECIMAL but have different digit and scale 
values, VAX BASIC uses the larger number of specified digits for the 
result. 


In the following example, variable A allows three digits to the left of 
the decimal point and two digits to the right. Variable B allows one 
digit to the left of the decimal point and three digits to the right. 


Example 


DECLARE DECIMAL(5,2) A 
DECLARE DECIMAL(4,3) B 


The result allows three digits to the left of the decimal point and three 
digits to the right. 


If one operand is DECIMAL and one is INTEGER, the INTEGER value 
is converted to a DECIMAL(d;s) data type as follows: 


— BYTE is converted to DECIMAL(3,0). 
— WORD is converted to DECIMAL(5,0). 
— LONG is converted to DECIMAL(10,0). 


VAX BASIC then determines the d and s values of the result by 
evaluating the d and s values of the operands as described above. 


Note that only INTEGER data types are converted to the DECIMAL data 
type. If one operand is DECIMAL and one is floating-point, the DECIMAL 
value is converted to a floating-point value. The total number of digits 
(d) in the DECIMAL value determines its new data type, as shown in 
Table 1-8. 
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Table 1-8: Result Data Types for DECIMAL Data 


aeeais Digits Floating-Point Operands 

in Operand SINGLE DOUBLE GFLOAT HFLOAT 
1-6 SINGLE DOUBLE GFLOAT HFLOAT 
7-15 DOUBLE DOUBLE GFLOAT HFLOAT 
16 DOUBLE DOUBLE HFLOAT  HFLOAT 
17-31 HFLOAT  HFLOAT MHFLOAT ~~ HFLOAT 


If the value of d is between 7 and 15, the operand is converted to: 


¢ DOUBLE if the floating-point operand is SINGLE or DOUBLE 
¢ GFLOAT if the floating-point operand is GFLOAT 
¢ HFLOAT if the floating-point operand is HFLOAT 


Thus, a DECIMAL(8,5) operand is converted to DOUBLE if the other 
operand is SINGLE or DOUBLE, to GFLOAT if the other operand is 
GFLOAT, and to HFLOAT if the other operand is HFLOAT. Note also that 
exponentiation of a DECIMAL data type returns a REAL value. 


See the VAX BASIC User Manual for tutorial information on data type 
interactions, conversions, and promotion rules in VAX BASIC numeric 
expressions. 


1.6.2 String Expressions 


String expressions are string entities separated by the plus sign (+). When 
used in a string expression, the plus sign concatenates strings. 


Example 


INPUT "Type two words to be combined"; A$, B$ 
C$ = A$ + BS 

PRINT C$ 

END 
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Output 


Type two words to be combined? long 
? word 


longword 


Ready 


1.6.3 Conditional Expressions 


Conditional expressions can be either relational or logical expressions. 
Numeric relational expressions compare numeric operands to determine 
whether the expression is true or false. String relational expressions 
compare string operands to determine which string expression occurs first 
in the ASCII collating sequence. 


Logical expressions contain integer operands and logical operators. VAX 
BASIC determines whether the specified logical expression is true or false 
by testing the numeric result of the expression. Note that in conditional 
expressions, as in any numeric expression, when BYTE and WORD 
operands are converted to WORD and LONG, the specified operation 

is performed in the higher data type, and the result returned is also of 
the higher data type. When one of the operands is a negative value, this 
conversion will produce accurate but perhaps confusing results, because 
VAX BASIC performs a sign extension when converting BYTE and WORD 
integers to a higher integer data type. See Section 1.6.1.1 for information 
on integer conversion rules. 


1.6.3.1 Numeric Relational Expressions 


Operators in numeric relational expressions compare the values of two 
operands and returns either a -1 if the relation is true, or a zero if the 
relation is false. The data type of the result is the default integer type. 
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Example 1 


A = 10 

B = 15 

X% = (A <> B) 
IF X% = -1% 


THEN PRINT 'Relationship is true' 

ELSE IF X% = 0 
THEN PRINT 'Relationship is false' 
END IF 

END IF 


Output 1 


Relationship is true 


Example 2 


A = 10 

B = 15 

XA =A=B 

IF X% = -1% 

THEN PRINT 'Relationship is true' 

ELSE IF X% = 0 
THEN PRINT ‘Relationship is false' 
END IF 

END IF 


Output 2 


Relationship is false 


Table 1-9 shows how numeric operators work in numeric relational 
expressions. 


Table 1-9: Numeric Relational Operators 


Operator Example Meaning 

7 A=B A is equal to B. 

= A <B A is less than B. 

- A> B A is greater than B. 
<=.0r-= < A A= B A is less than or equal to B. 
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Table 1-9 (Cont.): Numeric Relational Operators 


Operator Example Meaning 

> = Or => A>=B A is greater than or equal to B. 

<> or A <> B A is not equal to B. 

oP 

== A==B A and B will PRINT the same if they are equal to 


six significant digits. However, if one value prints 
in explicit notation and the other value prints in E 
format notation, the relation will always be false. 


1.6.3.2 String Relational Expressions 


Operators in string relational expressions determine how VAX BASIC 
compares strings. The VAX BASIC compiler determines the value of each 
character in the string by converting it to its ASCII value. ASCII values 
are listed in Appendix C in this manual. VAX BASIC compares the strings 
character by character, left to right, until it finds a difference in ASCII 
value. 


In the following example, VAX BASIC compares A$ and B$ character by 

character. The strings are identical up to the third character. Because the 
ASCII value of Z (90) is greater than the ASCII value of C (67), A$ is less 
than B$. VAX BASIC evaluates the expression A$ < B$ as true (-1) and 
prints “ABC comes before ABZ”. 


Example 


A$ = ‘ABC! 


THEN PRINT 'ABC comes before ABZ' 
ELSE IF A$ == B$ 
THEN PRINT 'The strings are identical' 
ELSE IF A$ > B$ 
THEN PRINT 'ABC comes after ABZ' 
ELSE PRINT 'Strings are equal but not identical’ 
END IF 
END IF 
END IF 
END 
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If two strings of differing lengths are identical up to the last character in 
the shorter string, VAX BASIC pads the shorter string with spaces (ASCII 
value 32) to generate strings of equal length, unless the operator is the 
double equal sign (==). If the operator is the double equal sign, VAX 
BASIC does not pad the shorter string. 
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In the following program, VAX BASIC compares “ABCDE” to “ABC ” 

to determine which string comes first in the collating sequence. “ABC ” 
comes before “ABCDE” because the ASCII value for space (32) is lower 
than the ASCII value of D (68). Then VAX BASIC compares “ABC ” with 
“ABC” using the double equal sign and determines that the strings do 
not match exactly without padding. The third comparison uses the single 
equal sign. VAX BASIC pads “ABC” with spaces and determines that the 
two strings match with padding. 


Example 
A$ = 'ABCDE! 
B$ = 'ABC! 


PRINT 'B$ comes before A$' IF B$ < A$ 

PRINT 'A$ comes before B$' IF A$ < B$ 

C$ = 'ABC ' 

IF B$ == C$ 
THEN PRINT 'B$ exactly matches C$' 
ELSE PRINT 'B$ does not exactly match C$' 

END IF 

IF BS = C$ 
THEN PRINT 'B$ matches C$ with padding' 
ELSE PRINT 'B$ does not match C$' 

END IF 


Output 

B$ comes before A$ 

B$ does not exactly match C$ 
B$ matches C$ with padding 


Table 1-10 shows how numeric operators work in string relational expres- 
sions. 


Table 1-10: String Relational Operators 


Operator Example Meaning 
= A$ = BS Strings A$ and B§ are identical after the shorter 


string has been padded with spaces to equal the 
length of the longer string. 


< A$ < B$ String A$ occurs before string B$ in ASCII 
sequence. 
i A$ > B$ String A$ occurs after string B$ in ASCII sequence. 


<=or=< A$ <=B$ String A$ is identical to or precedes string B$ in 
ASCII sequence. 
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Table 1—10 (Cont.): String Relational Operators 


Operator Example Meaning 

>=or=> A$ >=B$ String A$ is identical to or follows string B$ in 
ASCII sequence. 

<> OF A$ <> String A$ is not identical to string B$. 

aa BS 


== A$ == BS Strings A$ and B§ are identical in composition 
and length, without padding. 


VAX BASIC treats unquoted strings typed in response to the INPUT 
statement differently from quoted strings; it does so by ignoring leading 
and trailing spaces and tabs. For example, it evaluates the quoted strings 
“ABC” and “ABC ” as equal but not identical because the == operator 
does not pad the shorter string with spaces. When you input those same 
strings as unquoted strings in response to the INPUT prompt, VAX BASIC 
evaluates them as equal and identical because it ignores the trailing 
spaces. The LINPUT statement, on the other hand, treats unquoted strings 
as string literals, so the trailing spaces are part of the string, and VAX 
BASIC evaluates the strings as equal, but not identical. 


1.6.3.3. Logical Expressions 


A logical expression can have one of the following formats: 


e A unary logical operator and one integer operand 
¢ Two integer operands separated by a binary logical operator 
e One integer operand 


Logical expressions are valid only when the operands are integers. If 

the expression contains two integer operands of differing data types, the 
resulting integer has the same data type as the higher integer operand. 
For instance, the result of an expression that contains a BYTE integer and 
a WORD integer would be a WORD integer. Table 1-6 shows how integer 
data types interact with each other in expressions. 


VAX BASIC determines whether the condition is true or false by testing 
the result of the logical expression to see whether any bits are set. If 

no bits are set, the value of the expression is zero and it is evaluated as 
false; if any bits are set, the value of the expression is nonzero, and the 
expression is evaluated as true. VAX BASIC generally accepts any nonzero 
value in logical expressions as true. However, logical operators can return 
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unanticipated results unless —1 is specified for true values and zero for 
false. Table 1-11 lists the logical operators. 


NOTE 


DIGITAL recommends that you use logical operators on the 
results of relational expressions to avoid obtaining unanticipated 


results. 


Table 1-11: 


Operator 
NOT 


AND 


OR 


XOR 


EQV 


IMP 


Example 
NOT A% 


A% AND B% 


A% OR B% 


A% XOR B% 


A% EQV B% 


A% IMP B% 


Logical Operators 


Meaning 

The bit-by-bit complement of A%. If A% is true 
(-1), NOT A% is false (0). 

The logical product of A% and B%. A% AND 
B% is true only if both A% and B% are true. 
The logical sum of A% and B%. A% OR B% 

is false only if both A% and B% are false; 
otherwise, A% OR B% is true. 

The logical exclusive OR of A% and B%. A% 
XOR B% is true if either A% or B% is true but 
not if both are true. 

The logical equivalence of A% and B%. A% 
EQV B% is true if A% and B% are both true or 
both false; otherwise the value is false. 

The logical implication of A% and B%. A% IMP 


B% is false only if A% is true and B% is false; 
otherwise, the value is true. 


The truth tables in Figure 1-1 summarize the results of these logical 
operations. Zero is false; —1 is true. 
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Figure 1-1: Truth Tables 


NOT A% A% OR B% 


—1 0 
0 —1 
—1 
—1 


A% AND B% A% EQV B% 


4 
0 
0 

| 


A% XOR B% A% IMP B% 


0 —1 
—1 —1 
—1 0 
0 —1 
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The operators XOR and EQV are logical complements. 


In the following example, the values of A% and B% both test as true 
because they are nonzero values. However, the logical AND of these two 
variables returns an unanticipated result of false. 
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Example 

AY = 2% 

BY = 4% 

IF A% THEN PRINT 'A% IS TRUE’ 

IF BY% THEN PRINT ‘B% IS TRUE' 

IF A% AND BY THEN PRINT 'A% AND BY% IS TRUE' 
ELSE PRINT 'A% AND B% IS FALSE' 

END 


Output 
AY, IS TRUE 


BY IS TRUE 
AY, AND BY IS FALSE 


The program returns this seemingly contradictory result because logical 
operators work on the individual bits of the operands. The 8-bit binary 
representation of 2% is 


00000010 
The 8-bit binary representation of 4% is 
00000100 


Each value tests as true because it is nonzero. However, the AND opera- 
tion on these two values sets a bit in the result only if the corresponding 

bit is set in both operands. Therefore, the result of the AND operation on 
4% and 2% is 


00000000 
No bits are set in the result, so the value tests as false (zero). 


If the value of B% is changed to 6%, the resulting value tests as true 
(nonzero) because both 6% and 2% have the second bit set. Therefore, 
VAX BASIC sets the second bit in the result and the value tests as nonzero 
and true. 


The 8-bit binary representation of —1 is 
iiiaia4i14 4 


The result of -1% AND -1% is -1% because VAX BASIC sets bits in the 
result for each corresponding bit that is set in the operands. The result 
tests as true because it is a nonzero value. 
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Example 
AY = -1% 
BY = -1% 


IF A% THEN PRINT 'A% IS TRUE' 

IF B% THEN PRINT 'B% IS TRUE' 

IF A% AND B% THEN PRINT 'A% AND BY% IS TRUE' 
ELSE PRINT 'A% AND BY IS FALSE' 

END 


Output 


AY, IS TRUE 
BY’ IS TRUE 
AY, AND BY IS TRUE 


Your program may also return unanticipated results if you use the NOT 
operator with a nonzero operand that is not -1. 


In the following example, VAX BASIC evaluates both A% and B% as true 
because they are nonzero. NOT A% is evaluated as false (zero) because 
the binary complement of —1 is zero. NOT B% is evaluated as true because 
the binary complement of 2 has bits set and is therefore a nonzero value. 


Example 


A%=-1% 
B4=2 
IF A% THEN PRINT 'A% IS TRUE’ 
ELSE PRINT 'A% IS FALSE' 
IF B% THEN PRINT 'B% IS TRUE' 
ELSE PRINT 'B% IS FALSE' 
IF NOT A% THEN PRINT 'NOT A% IS TRUE' 
ELSE PRINT 'NOT A% IS FALSE’ 
IF NOT BY THEN PRINT 'NOT BY IS TRUE' 
ELSE PRINT 'NOT B% IS FALSE' 
END 


Output 


AY, IS TRUE 

Bi IS TRUE 

NOT A% IS FALSE 
NOT BY IS TRUE 


1.6.4 Evaluating Expressions 
VAX BASIC evaluates expressions according to operator precedence. Each 


arithmetic, relational, and string operator in an expression has a position 
in the hierarchy of operators. The operator’s position informs VAX BASIC 
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of the order in which to perform the operation. Parentheses can change 
the order of precedence. 


Table 1-12 lists all operators as VAX BASIC evaluates them. Note that 

e¢ Operators with equal precedence are evaluated logically from left to 
right. 

e VAX BASIC evaluates expressions enclosed in parentheses first, even 


when the operator in parentheses has a lower precedence than that 
outside the parentheses. 


e ©The addition (+) and multiplication (*) operators are evaluated in 
algebraic order. 


Table 1-12: Numeric Operator Precedence 
Operator Precedence 
** OY - 

— (unary minus) or + (unary plus) 
* or / 

+ or - 

+ (concatenation) 

all relational operators 

NOT 

AND 

OR, XOR 

IMP 

EQV 11 


eo DAN DBD oO FF WN 


a 
la) 


For example, VAX BASIC evaluates the expression A = 15°2 + 12°2 - 
(35 * 8) in five steps: 


1. 152.5229 Exponentiation (leftmost expression) 
2 12°2 = 144 Exponentiation 

3. 225 + 144 = 369 Addition 

4 (35 * 8) = 280 Multiplication 

5 369 - 280 = 89 Subtraction 
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There is one exception to this order of precedence: when an operator that 
does not require operands on either side of it (such as NOT) immediately 
follows an operator that does require operands on both sides (such as the 
addition operator (+)), VAX BASIC evaluates the second operator first. 
For example: 


AY + NOT BY + C% 
This expression is evaluated as 
(A% + (NOT B%)) + Ch 


VAX BASIC evaluates the expression NOT B before it evaluates the 
expression A + NOT B. When the NOT expression does not follow the 
addition (+) expression, the normal order of precedence is followed: 


NOT AZ + BA + C% 
This expression is evaluated as: 
NOT ((A% + BZ) + C %) 


VAX BASIC evaluates the two expressions (A% + B%) and ((A% + B%) 
+ C%) because the + operator has a higher precedence than the NOT 
operator. 


VAX BASIC evaluates nested parenthetical expressions from the inside 
out. 


In the following program, VAX BASIC evaluates the parenthetical expres- 
sion A quite differently from expression B. For expression A, VAX BASIC 
evaluates the innermost parenthetical expression (25 + 5) first, then the 
second inner expression (30 / 5), then (6 * 7), and finally (42 + 3). For 
expression B, VAX BASIC evaluates (5 / 5) first, then (1 * 7), then (25 + 7 
+ 3) to obtain a different value. 


Example 

A = ((((25 + 5) / 5) * 7) + 3) 
PRINT A 
B=25+5/5%*7+3 

PRINT B 

Output 


45 
35 
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1.7. Program Documentation 


Documentation within a program clarifies and explains source program 
structure. These explanations, or comments, can be combined with code 
to create a more readable program without affecting program execution. 
Comments can appear in two forms: 


e Comment fields (including empty statements) 
e REM statements 


1.7.1 Comment Fields 


A comment field begins with an exclamation point (!) and ends with a 
carriage return. You supply text after the exclamation point to document 
your program. You can specify comment fields while creating VAX BASIC 
programs at DCL level as well as in the BASIC environment. In both 
cases, VAX BASIC does not execute text in a comment field. 


Example 


! FOR loop to initialize list Q 
FOR I = 1 TO 10 

Q(I) = 0 ! This is a comment 
NEXT I 
! List now initialized 


VAX BASIC executes only the FOR...NEXT loop. The comment fields, 
preceded by exclamation points, are not executed. 


Comment fields help make your program more readable and allow you 
to format your program into readily visible logical blocks. They can also 
serve as target lines for GOTO and GOSUB statements. 
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Example 


! Square root program 
! 


INPUT ‘Enter a number';A 
PRINT 'SQR of ';A;'is ';SQR(A) 
! 

! More square roots? 

' 


INPUT 'Type "Y" to continue, press RETURN to quit' ;ANS$ 


GOTO 10 IF ANS$ = "Y" 
j 


END 


You can also use an exclamation point to terminate a comment field, but 
this practice is not recommended. You should make sure that there are 
no exclamation points in the comment field itself; otherwise, VAX BASIC 
treats the text remaining on the line as source code. 


NOTE 


Comment fields in DATA statements are invalid; the VAX 
BASIC compiler treats the comments as additional data. 


Empty statements consist of a line number and an exclamation point. 
Empty statements can make your program more legible by increasing the 
amount of “white space” and visually separating logical program segments. 
In the following example, lines 100 and 300 are empty statements: 


Example 


100 ! 
! FOR loop to initialize list Q 
' 
200 FOR I = 1 TO 10 
Q(I) = 0 ! This is a comment 
NEXT I 
300 ! 
! List is now initialized 


In general, empty statements can be used to make a program more legible 
and organized. 
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1.7.2 REM Statements 


A REM statement begins with the REM keyword and ends when VAX 
BASIC encounters a new line number. The text you supply between the 
REM keyword and the next line number documents your program. Like 
comment fields, REM statements do not affect program execution. VAX 
BASIC ignores all characters between the keyword REM and the next 
line number. Therefore, the REM statement can be continued without the 
ampersand continuation character and should be the only statement on 
the line or the last of several statements in a multi-statement line: 


Example 


REM This is an example 
A=5 
B=10 
REM A equals 5 
B equals 10 
PRINT A, B 


The REM statement is nonexecutable. When you transfer control to a 
REM statement, VAX BASIC executes the next executable statement that 
lexically follows the referenced statement. 


NOTE 


Because VAX BASIC treats all text between the REM statement 
and the next line number as commentary, REM should be used 
very carefully in programs that follow the implied continuation 
rules. REM statements are disallowed in programs without line 
numbers. 


In the following example, the conditional GOTO statement in line 20 
transfers program control to line 10. VAX BASIC ignores the REM com- 
ment on line 10 and continues program execution at line 20. 


Example 


10 REM ** Square root program 

20 INPUT 'Enter a number';A 
PRINT 'SQR of ';A;'is ';SQR(A) 
INPUT 'Type "Y" to continue, press RETURN to quit' ; ANS$ 
GOTO 10 IF ANS$ = "yY" 

40 END 
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Chapter 2 
BASIC Environment Commands 


Environment commands are commands that you use in the BASIC envi- 
ronment. With environment commands, you can display, edit, and merge 
VAX BASIC programs, set compiler defaults, move VAX BASIC source 
programs to and from storage, and execute programs. This chapter lists 
alphabetically all of the compiler commands that can be used within the 
BASIC environment. For information on immediate mode and calculator 
mode statements, see the VAX BASIC User Manual. 
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! your-comment 





! your-comment 


You can enter comments while in the BASIC environment by typing an 
exclamation point (!) and the comment. 


Format 


!  your-comment 
Syntax Rules 


1. The exclamation point must be the first character on the line. 
2. You cannot continue a comment over more than one line. 


Remarks 
None. 
Examples 
Example 1 
Ready 


! Comments here ... 
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! your-comment 


Example 2 
$ TYPE BUILD_SPECIAL.COM 


$ SET VERIFY 

$ BASIC 

!+ 

! Set the compilation options by uncommenting 
! the appropriate ones. 
! SET LIST 

SET WORD 

SET DEBUG 

1+ 

! Get the source module. 
!- 

OLD SPECIAL 

t+ 

! Compile it. 

1. 

COMPILE 

t+ 

! All done. 

1- 

EXIT 
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S$ system-command 


S system-command 


You can execute a DCL command while in the BASIC environment by 
typing a dollar sign ($) before the command. VAX BASIC passes the 
command to the operating system for execution. The context of the BASIC 
environment and the program currently in memory do not change. 


Format 


$  system-command 
Syntax Rules 


VAX BASIC passes system-command directly to the VAX/VMS operating 
system without checking for validity. 


Remarks 


1. The terminal displays any error messages or output that the command 
generates. 


2. Control returns to the BASIC environment after the command exe- 
cutes. The context (source file status, loaded modules, and so on) of 
the BASIC environment and the program currently in memory do not 
change unless the command causes the operating system to abort VAX 
BASIC or log you out. 


3. The command you specify executes within the context of a subprocess. 
Consequently, commands such as the DCL command SET execute 
only within the subprocess and do not affect the process running VAX 
BASIC. 
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S$ system-command 


Ready 


$ SHOW PROTECTION 
SYSTEM=RWED, OWNER=RWED, GROUP=RWED, WORLD=RE 


Ready 
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APPEND 


APPEND 


The APPEND command merges an existing VAX BASIC source program 
with the program currently in memory. 


Format 
APPEND /file-spec] 


Syntax Rules 


File-spec is the name of the VAX BASIC program you want to merge with 
the program currently in memory. The default file type is BAS. 


Remarks 


1. You cannot specify the APPEND command on programs that do not 
contain line numbers. 


2. If you type APPEND without specifying a file name, VAX BASIC 
prompts with 


Append file name-- 


You should respond with a file name. If you respond with a car- 
riage return and no file name, VAX BASIC searches for a file 
named NONAME.BAS. If the VAX BASIC compiler cannot find 
NONAME.BAS, VAX BASIC signals the error “Can’t find file or 
account” (ERR=5). 


3. You can append the contents of file-spec to a source program that is 
either called into memory with the OLD command or created in the 
BASIC environment. If there is no program in memory, VAX BASIC 
appends the file to an empty program with the default file name 
NONAME. 
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APPEND 


4. If file-spec contains a VAX BASIC line with the same line number as a 
line of the program in memory, the line in the appended file replaces 
the line of the program in memory. Otherwise, VAX BASIC inserts 
appended lines into the program in memory in sequential, ascending 
line number order. 


5. The APPEND command does not change the name of the program in 
memory. 


6. If you have not saved the appended version of the program, VAX 
BASIC signals the warning “Unsaved change has been made, CTRL/Z 
or EXIT to exit” the first time you try to leave the BASIC environment. 


Ready 

New FIRST_TRY.BAS 

Ready 

10 PRINT "First program" 

APPEND NEW_PROG.BAS 

Ready 

LIST 

10 PRINT "First Program" 

20 PRINT "This section has been appended" 
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ASSIGN 


ASSIGN 


The ASSIGN command equates a logical name to a complete file specifi- 
cation, a device, or another logical name within the context of the BASIC 
environment. 


Format 


ASSIGN = equiv-namef[:] log-namef[:] 
Syntax Rules 


1. Equiv-name specifies the file specification, device, or logical name to be 
assigned a logical name. If you specify a physical device name, you 
must terminate it with a colon (:). 


2. Log-name is the 1- to 63-character logical name to be associated with 
equiv-name. You can specify a logical name for any portion of a file 
specification. If the logical name translates to a device name, and will 
be used in place of a device name in a file specification, you must 
terminate it with a colon (:). 


3. If log-name has more than 63 characters, VAX BASIC signals the error 
“Invalid logical name”. . 


Remarks 


1. When the logical name assignment supersedes another logical name 
previously assigned, VAX BASIC displays the message “Previous 
logical name assignment replaced”. 


2. Logical names assigned with the ASSIGN command are placed in the 
process logical name table and remain there until you exit the BASIC 
environment. 
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ASSIGN 


ASSIGN [HENRY.BAS] PRO: 
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COMPILE 


COMPILE 


The COMPILE command converts a VAX BASIC source program to an 
object module and writes the object file to disk. 


Format COMPILE / file-spec ] [ /qualifier |... 


Command Qualifiers 
/[NOJANSI_STANDARD 
/{NOJAUDIT [ sep text-entry ] 
/{NO]BOUNDS_CHECK 


/BYTE 

/{NO]JCROSS_REF [ sep [NO]JKEYWORDS |] 
/[NO]DEBUG 

/DECIMAL_SIZE sep (d,s) 

/DOUBLE 


/{NO]FLAG [ sep ( flag-clause,... ) ] 
/GFLOAT 

/HFLOAT 

/{NO]JLINES 

/{(NO]LIST 

/LONG 

/([NOJMACHINE__CODE 
/{NOJOBJECT 

/[NOJOVERFLOW |[ sep (data-type,...) ] 
/[NO]JROUND 

/{NO]JSETUP 

/[NOJSHOW [ sep ( show-item,... ) ] 
/SINGLE 

/[NO]JSYNTAX_CHECK 
/{NO]TRACEBACK 
/TYPE_DEFAULT sep default-clause 
/VARIANT sep int-const 
/[NO]WARNINGS [ sep warn-clause ] 
/WORD 
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Defaults 
/NOANSI_STANDARD 
/NOAUDIT 
/BOUNDS__CHECK 
/LONG 

/NOCROSS_REF 
/NODEBUG 

/DECIMAL _SIZE=(15,2) 
/SINGLE 

/NOFLAG 

/SINGLE 

/SINGLE 

/LINES 

/NOLIST 

/LONG 

/NOMACHINE 

/OBJECT 
/OVERFLOW=(INTEGER,DECIMAL) 
/NOROUND 

/SETUP 

/SHOW 

/SINGLE 

/NOSYNTAX —CHECK 
/TRACEBACK 
/TYPE_DEFAULT=REAL 
/VARIANT=0 
/WARNINGS 

/LONG 


Syntax Rules 


Remarks 


COMPILE 


File-spec specifies a name for the output file or files. If you do not 
provide a file-spec, the VAX BASIC compiler uses the name of the 
program currently in memory for the file name, a default file type of 
OBJ for the object file, and a default file type of LIS for the listing file, 
if a listing file is requested. 


File-spec can precede or follow any qualifier. 
/Qualifier specifies a qualifier keyword that sets a VAX BASIC default. 


You can abbreviate all positive qualifiers to the first three letters of the 
qualifier keyword. You can abbreviate a negative qualifier to NO and 
the first three letters of the qualifier keyword. 


In cases of ambiguous or erroneous qualifiers, VAX BASIC signals 
“Unknown qualifier”, and the program does not compile. When 
qualifiers conflict, VAX BASIC compiles the program using the last 
specified conflicting qualifier. For example, the following command 
line causes VAX BASIC to compile the program currently in memory 
but does not cause VAX BASIC to create an OBJ file. 


COMPILE/OBJ/NOOBJ 


There must be a program in memory, or the COMPILE command does 
not execute; VAX BASIC does not signal an error or warning. 


If an object file for the program already exists in your directory, VAX 
BASIC creates a new version of the OBJ file. 

You should not specify both a file name and file type. For example, 
if you enter the following command line, VAX BASIC creates two 
versions of NEWOBJ.FIL: 


COMPILE NEWOBJ.FIL/LIS/OBJ 


The first version, NEWOBJ.FIL;1, is the listing file; the second version, 
NEWOBJ.FIL;2, is the object file. If you specify only a file name, VAX 
BASIC uses the OBJ and LIS file type defaults when creating these 
files. 

Use the COMPILE/NOOBJECT command to check your program for 
errors without producing an object file. 
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COMPILE 


4. When you exit from the BASIC environment, all options set with qual- 
ifiers return to the system default values. Use the SHOW command to 
display your system defaults before setting any qualifiers. 


Command Qualifiers 


/{[NOJANSI_STANDARD 

The /ANSI_STANDARD qualifier causes VAX BASIC to compile pro- 
grams according to the ANSI Minimal BASIC standard and to flag syntax 
that does not conform to the standard. The /NOANSI_STANDARD 
qualifier causes VAX BASIC not to compile the program according to the 
ANSI Minimal BASIC standard. The default is /NOANSI_STANDARD. 


See the VAX BASIC User Manual for more information on the ANSI 
Minimal BASIC Standard. 


/ANojAuDIT [ { * } { str-lit \ ] 


file-spec 
The /AUDIT qualifier causes VAX BASIC to include a history list entry in 
the CDD data base when a CDD definition is extracted. Str-lit is a quoted 
string. File-spec is a text file. The history entry includes 


¢ The contents of str-lit, or up to the first 64 lines in the file specified by 
file-spec 

e The name of the program module, process, user name, and user UIC 
that accessed the CDD 

e The time and date of the access 

e A note that access was made by the VAX BASIC compiler 

e A note that access was an extraction 


If you specify /NOAUDIT VAX BASIC does not include a history list 
entry. /NOAUDIT is the default. 


/[NOJBOUNDS_CHECK 

The /BOUNDS_CHECK qualifier causes VAX BASIC to perform range 
checks on array subscripts. With bounds checking enabled, VAX BASIC 
checks that all subscript references are within the array boundaries set 
when the array was declared. If the subscript bounds are not within the 
bounds initially declared for the array, VAX BASIC signals an error mes- 
sage. If you specify /NOBOUNDS_CHECK VAX BASIC does not check 
that all subscript references are within the array bounds set. /BOUNDS_ 
CHECK is the default. 
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COMPILE 


/BYTE 

The /BYTE qualifier causes VAX BASIC to allocate 8 bits of storage as the 
default for all integer data not explicitly typed in the program. Untyped 
integer values are treated as BYTE values and must be in the BYTE range 
or VAX BASIC signals the error “Integer error or overflow.” Table 1-2 in 
this manual lists VAX BASIC data types and ranges. By default, the VAX 
BASIC compiler allocates 32 bits of storage. 


/{NOJCROSS_REFERENCE [ { © } [NOJKEYWORDS ] 


If you use the /CROSS_REFERENCE qualifier with the /LIST qualifier 
when you compile your program, the VAX BASIC compiler includes cross- 
reference information in the program listing file. If you specify /CROSS_ 
REFERENCE=KEYWORDS, VAX BASIC also cross-references VAX BASIC 
keywords used in the program. If you specify /NOCROSS_REFERENCE, 
VAX BASIC does not include a cross reference section in the compiler 
listing. The default is /NOCROSS_REFERENCE. 


/[NO]DEBUG 

The /DEBUG qualifier appends to the object file information on symbolic 
references and line numbers. This information is used by the VAX/VMS 
Debugger when you debug your program. When you specify the /DEBUG 
qualifier on the COMPILE command, you cause the debugger to be 
invoked automatically when the program is run at DCL level (unless 

you specify RUN/NODEBUG). If you specify COMPILE/NODEBUG, 
information on program symbols and line numbers is not included in the 
object file. The default is /NODEBUG. 


See the VAX BASIC User Manual for more information on using the 
VAX/VMS Debugger. 


/DECIMAL_SIZE { * } (d,s) 


The /DECIMAL _SIZE qualifier allows you to specify the default size and 
precision for all DECIMAL data not explicitly assigned size and precision 
in the program. You specify the total number of digits (d) and the number 
of digits to the right of the decimal point (s). VAX BASIC signals the error 
“Decimal error or overflow” (ERR=181) when DECIMAL values are outside 
the range specified with this qualifier. See Table 1-2 in this manual for 
more information on the storage and range of packed decimal data. The 
default is /DECIMAL _SIZE=(15,2). 
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COMPILE 


/DOUBLE 

The /DOUBLE qualifier causes VAX BASIC to allocate 64 bits of storage 
in D_floating format as the default size for all floating-point data not 
explicitly typed in the program. Untyped floating-point values are treated 
as DOUBLE values and must be in the DOUBLE range or VAX BASIC 
signals the error “Floating-point error or overflow.” Table 1-2 in this 
manual lists VAX BASIC data types and ranges. The default is /SINGLE. 


: [NO]JBP2COMPATIBILITY 
[INOJFLAG [{ = } ( { [NO]DECLINING } vod J 
The /FLAG qualifier causes VAX BASIC to provide compile-time informa- 
tion about program elements that are not compatible with BASIC-PLUS-2 
or that DIGITAL designates as not recommended for new program devel- 


opment. For more information on source code that is incompatible with 
with BASIC-PLUS-2, see Appendix A in this manual. 


If you specify the DECLINING clause, VAX BASIC will flag the following 
source code as declining: 


e CVT$$ (use EDIT$) 


° CVT$%, CVT$F, CVT%$, CVTF$, AND SWAP% (use multiple MAP 
statements) 


e DEF* functions (use DEF functions) 
e FIELD statements (use MAP DYNAMIC and REMAP) 
e GOTO line-num% (do not use the integer suffix with a line number) 


The default is /NOFLAG. 


/GFLOAT 

The /GFLOAT qualifier causes VAX BASIC to allocate 64 bits of storage 
in G_floating format as the default size for all floating-point data not 
explicitly typed in the program. Untyped floating-point values are treated 
as G_floating values and must be in the G_floating range or VAX BASIC 
signals “Floating-point error or overflow.” Table 1-2 in this manual lists 
VAX BASIC data types and ranges. The default is /SINGLE. 


/HFLOAT 

The /HFLOAT qualifier causes VAX BASIC to allocate 128 bits of storage 
in H_floating format as the default size for all floating-point data not 
explicitly typed in the program. Untyped floating-point values are treated 
as H_floating values and must be in the H_floating range or VAX BASIC 
signals “Floating-point error or overflow.” Table 1-2 in this manual lists 
VAX BASIC data types and ranges. The default is /SINGLE. 
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COMPILE 


/(NOJLINES 

The /LINES qualifier includes line number information in object modules. 
If you specify /NOLINES VAX BASIC does not include line number 
information in object modules. If you specify /NOLINES in a program 
containing a RESUME statement or the run-time ERL function, VAX 
BASIC issues a warning that the /NOLINES qualifier has been overridden. 
The default is /LINES. 


A(NOJLIST 

The /LIST qualifier causes VAX BASIC to produce a compiler listing file. 
This compiler listing generated by the /LIST qualifier contains a memory 
allocation map. By default, the name of the listing file is the same as the 
name of the first program module specified, and has a default file type of 
LIS. If you specify /NOLIST VAX BASIC does not generate a compiler 
listing. /NOLIST is the default. 


/LONG 

The /LONG qualifier causes VAX BASIC to allocate 32 bits of storage as 
the default size for all integer data not explicitly typed in the program. 
Untyped integer values are treated as LONG values and must be in the 
LONG range or VAX BASIC signals the error “Integer error or overflow.” 
Table 1-2 in this manual lists VAX BASIC data types and ranges. /LONG 
is the default. 


/[NOJMACHINE_CODE 

When you specify the /MACHINE_CODE qualifier with the /LIST 
qualifier in the COMPILE command, VAX BASIC includes the machine 
code generated by the compilation in the program listing file. If you 
specify /NOMACHINE_CODE, VAX BASIC does not include a machine 
code section in the listing file. /NOMACHINE—CODE is the default. 


/(NOJOBJECT 

The /OBJECT qualifier generates an object module with the same file 
name as the program and a default file type of OBJ. The /NOOBJECT 
qualifier allows you to check your program for errors without creating an 
object file. /OBJECT is the default. 


/AINOJOVERFLOW [ { = }({ NT GEe } dT 


The /OVERFLOW qualifier causes VAX BASIC to report arithmetic 
overflow for operations on integer or packed decimal data, or both. If 
you specify /NOOVERFLOW, VAX BASIC does not report arithmetic 
overflows. The default is /OVERFLOW=(INTEGER,DECIMAL). 
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COMPILE 


/ALNOJROUND 

The /ROUND qualifier causes VAX BASIC to round rather than truncate 
DECIMAL values. If you specify /NOROUND, VAX BASIC truncates 
DECIMAL values. The default is /NOROUND. 


/{NOJSETUP 

The /SETUP qualifier causes VAX BASIC to make calls to the Run-Time 
Library to set up the stack for VAX BASIC variables, set up dynamic 
string and array descriptors, initialize variables, and enable VAX BASIC 
error handling. If you specify the /NOSETUP qualifier, VAX BASIC 
will attempt to optimize your program by omitting these calls. If your 
program contains any of the following elements, VAX BASIC provides an 
informational diagnostic and does not optimize your program: 


e CHANGE statements 

e DEF or DEF* statements 

e Dynamic string variables 

e Executable DIM statements 

e EXTERNAL string functions 

e MAT statements 

e MOVE statements for an entire array 

e ON ERROR statements 

¢ READ statements 

¢ REMAP statements 

¢ RESUME statements 

e WHEN blocks 

e All graphics statements 

e String concatenation 

e Built-in string functions 

¢ ~=©Virtual array declarations 

Note that program modules compiled with the /NOSETUP qualifier 
cannot perform I/O and have no error-handling capabilities. If an error 


occurs in such a module, the error is resignaled to oe calling program. 
The default is /SETUP. 
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COMPILE 


[NO]CDD_DEFINITIONS 
2 [NOJENVIRONMENT 
/INOJSHOW [ { _ } ({ [NOJINCLUDE ed 
7 [NO]JMAP 
[NOJOVERRIDE 
The /SHOW qualifier (when used with the /LIST qualifier) tells VAX 
BASIC what to include in the compiler listing file. You can specify the 
following /SHOW qualifier items: 


e CDD_DEFINITIONS causes VAX BASIC to include a section of 
translated CDD definitions 

¢ ENVIRONMENT causes VAX BASIC to include a list compilation 
qualifiers in effect 

e INCLUDE causes VAX BASIC to include a section on the contents of 
any %INCLUDE files 


e¢ MAP causes VAX BASIC to include a storage allocation map section 


¢ OVERRIDE cancels the effect of all %NOLIST directives in the source 
program 


For example, if you specify the following command, VAX BASIC includes 
a storage allocation map section in the compiler listing: 


COMPILE/LIST/SHOW=MAP 


If you specify a /SHOW qualifier but do not specify any /SHOW items, 

VAX BASIC includes all the aforementioned sections in the listing. If you 
specify /NOSHOW, VAX BASIC does not add any additional sections to 
the compiler listing. The default is /SHOW. 


/SINGLE 

The /SINGLE qualifier causes VAX BASIC to allocate 32 bits of storage 
in F_floating format as the default size for all floating-point data not 
explicitly typed in the program. Untyped floating-point values are treated 
as SINGLE values and must be in the SINGLE range or VAX BASIC 
signals the error “Floating-point error or overflow.” Table 1-2 in this 
manual lists VAX BASIC data types and ranges. The default is /SINGLE. 


AINOJSYNTAX_CHECK 

The /SYNTAX_—CHECK qualifier causes VAX BASIC to perform syntax 
checking after each program line is typed. If you specify /NOSYNTAX— 
CHECK, VAX BASIC does not perform syntax checking after each program 
line is typed. The default is /NOSYNTAX—CHECK. 
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COMPILE 


/ALNO]JTRACEBACK 

The /TRACEBACK qualifier causes VAX BASIC to include traceback 
information in the object file that allows reporting of the sequence of 
calls that transferred control to the statement where an error occurred. 
The /NOTRACEBACK qualifier tells VAX BASIC not to include traceback 
information in the object file. The default is /TRACEBACK. 


REAL 
/TYPE_DEFAULT { © \ pil bart 


EXPLICIT 
The /TYPE_DEFAULT qualifier sets the default data type (REAL, 
INTEGER, or DECIMAL) for all data not explicitly typed in your program 
or specifies that all data must be explicitly typed (EXPLICIT). 


e REAL specifies that all data not explicitly typed is floating-point data 
of the default size (SINGLE, DOUBLE, GFLOAT, or HFLOAT). 


e INTEGER specifies that all data not explicitly typed is integer data of 
the default size (BYTE, WORD, or LONG). 


e DECIMAL specifies that all data not explicitly typed is packed decimal 
data of the default size. 


e¢ EXPLICIT specifies that all data in a program must be explicitly typed. 
Implicitly declared variables cause VAX BASIC to signal an error. 


The default is TYPE_DEFAULT=REAL. 


/VARIANT | * } int-const 


The /VARIANT qualifier establishes int-const as a value to be used in 
compiler directives. The variant value can be referenced in a lexical 
expression with the lexical function, % VARIANT. Int-const always has a 
data type of LONG. The default is /VARIANT=0. 


: \ { [NO]WARNINGS 
/INO]WARNINGS [ { > } { [NO]INFORMATIONALS J 


The /WARNINGS qualifier causes VAX BASIC to display warning or 
informational messages, or both. If you specify /WARNINGS but do 
not specify a warning clause, VAX BASIC displays both warnings and 
informational messages. If you specify /NOWARNINGS, VAX BASIC 
does not display warning and informational messages. The default is 
/WARNINGS. 
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Example 


COMPILE 


/WORD 

The /WORD qualifier causes VAX BASIC to allocate 16 bits of storage 
as the default for all integer data not explicitly typed in the program. 
Untyped integer values are treated as WORD values and must be in the 
range -32768 to 32767 or VAX BASIC signals the error “Integer error 
or overflow.” Table 1-2 in this manual lists VAX BASIC data types and 
ranges. The default is /LONG. 


In the following example, VAX BASIC compiles the program LETSGO and 
creates a new version of the object file as well as a listing file. In addition, 
VAX BASIC allocates 64 bits of storage in D_FLOAT format as the default 
for all floating point data not explicitly typed in the program. 


COMPILE LETSGO/DOUBLE/LIST 
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CONTINUE 


The CONTINUE command continues program execution after VAX BASIC 
executes a STOP statement or encounters a CTRL/C. 


Format 
CONTINUE 
Syntax Rules 
None. 
Remarks 
1. After a STOP statement or a CTRL/C, you can enter immediate mode 
commands and resume program execution with the CONTINUE 
command. 
2. After a STOP statement or a CTRL/C, you cannot resume program 
execution if you have made source code changes or additions. 
Example 


%BAS-I-STO, Stop 
-BAS-I-FROLINMOD, from line 25 in module ABC 
Ready 


CONTINUE 
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DELETE 


DELETE 


The DELETE command removes a specified line or range of lines from the 
program currently in memory. 


Format 


DELETE fine-num | ~ line-num 


,line-num... 


Syntax Rules 
None. 
Remarks 


1. You cannot specify the DELETE command on programs that do not 
contain line numbers. 


2. The separator characters (comma or hyphen) allow you to delete 
individual lines or a block of lines. 


e If you separate line numbers with commas, VAX BASIC deletes 
each specified line number. 


e If you separate line numbers with a hyphen, VAX BASIC deletes 
the inclusive range of lines. The lower line number must be 
specified first. If it is not specified first, the DELETE command has 
no effect. 

3. You can combine individual line numbers and line ranges in a single 
DELETE command. Note, however, that a line number range must be 
followed by a comma and not another hyphen, or VAX BASIC signals 
an error. 


4. VAX BASIC signals an error if there are no lines in the specified range 
or if you specify an illegal line number. 
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DELETE 
Examples 


Example 1 


DELETE 50 


Example 2 


DELETE 70-80, 110, 124 


Example 3 


DELETE 50,60,90-110 
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EDIT 


EDIT 


The EDIT command allows you to edit individual program lines in the 
BASIC environment while invoking an editor. EDIT with no arguments 
invokes a text editor and reads the current program into the editor’s buffer. 


Format 


EDIT [| /ine-num search-clause [ replace-clause ] ] 
search-clause: delim ung-str1 delim 


replace-clause: [ ung-str2 ] [ delim [ int-const1 ] [ ,int-const2 ] ] 
Syntax Rules 


Line-num specifies the line to be edited. 


2. Search-clause specifies the text you want to remove or replace. Unq- 
str1 is the search string you want to remove or replace. 


3. Replace-clause specifies the replacement text and the occurrence of the 
search string you want to replace. 


e Ung-str2 is the replacement string. 


e Int-const1 specifies the occurrence of ung-str1 you want to replace. 
If you do not specify an occurrence, VAX BASIC replaces the first 
occurrence of unq-str1. 


e Int-const2 specifies the line number of a block of program code 
where you want VAX BASIC to begin the search. 


4. Delim can be any printing character not used in unq-str1 or unq-str2. 
The examples for this command use the slash (/) as a delimiter. 
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EDIT 


Remarks 


The delim characters in search-clause must match, or VAX BASIC 
signals an error. . 


If the delimiter you use to signal the end of replace-clause does not 
match the delimiter used in search-clause, VAX BASIC does not signal 
an error and treats the end delimiter as part of unq-str2. 


VAX BASIC replaces or removes text in a program line as follows: 
e If unq-str1 is found, VAX BASIC replaces it with unq-str2. 

e If ung-str1 is not found, VAX BASIC signals an error. 

e If unq-str1 is null, VAX BASIC signals “No change made”. 

e = If ung-str2 is null, VAX BASIC deletes ung-str1. 


e VAX BASIC matches and replaces strings exactly as you type 
them. If ung-str1 is uppercase, VAX BASIC searches for an upper- 
case string. If it is lowercase, VAX BASIC searches for a lowercase 
string. 

VAX BASIC displays the edited line with changes after the EDIT 

command successfully executes. 


If you specify a line number with no text parameters, VAX BASIC 
displays the line. 


The EDIT command followed by a carriage return causes VAX BASIC 
to save your current source file in BASEDITMP.BAS and automatically 
invoke VAX EDT as the default text editor. 


At DCL level, you can override the default text editor. To do this, as- 
sign the logical name BASIC$EDIT to another editor such as VAXTPU 
or Language-Sensitive Editor before entering the BASIC environment. 
For instance, in the following example, BASIC$EDIT is defined to be 
TPU$EDIT. The EDIT command followed by a carriage return will 
then invoke VAXTPU as the default text editor. 


$ DEFINE BASIC$EDIT TPUSEDIT 


If you define BASIC$EDIT to be an editor other than VAX EDT, 
VAXTPU, or Language-Sensitive Editor, VAX BASIC spawns a subpro- 
cess to invoke the editor assigned to BASIC$EDIT. 
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Example 


EDIT 


9. When you finish editing your program and exit from the editor, the 
edited program is the program currently in memory, and the context of 
the BASIC environment is unchanged. Note that VAX BASIC deletes 
all versions of BASEDITMP.BAS when you return to VAX BASIC from 
the editor. 


Ready 

LIST 100 

100 NEW_STRING$ = LEFT$(STRING$, 12) 
EDIT 100 /LEFT$/RIGHT$/3 ,2 

LIST 100 

100 NEW_STRING$ = RIGHT$(STRING$, 12) 
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EXIT 


EXIT 


The EXIT command or CTRL/Z clears the memory and returns control to 
the operating system. 


Format 
- EXIT 


Syntax Rules 


None. 


Remarks 
If you type EXIT after creating a new program or editing an old program 
without first typing SAVE or REPLACE, VAX BASIC signals “Unsaved 
change has been made, CTRL/Z or EXIT to exit”. The message warns 
you that the new or revised program will be lost if you do not SAVE or 
REPLACE it. If you type EXIT again, VAX BASIC exits from the BASIC 
environment whether you have saved your changes or not. 

Example 
EXIT 
“%BASIC-W-CHANGES, unsaved change has been made, CTRL/Z or EXIT to exit 
Ready 
SAVE 
EXIT 
Ready 
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HELP 


HELP 


The HELP command displays online documentation for VAX BASIC 
commands, keywords, statements, functions, and conventions. 


Format 


HELP / ung-str J... 


Syntax Rules 


Remarks 


Ungq-str is a VAX BASIC topic, keyword, command, statement, func- 
tion, or convention. 


The first unq-str must be one of the topics described in the HELP file. 
If it is not, VAX BASIC displays a list of topics for you to choose from. 


You can specify a subtopic after the topic. Separate one unq-str from 
another with a space. 


You can use the asterisk (*) wildcard character in unq-str. VAX BASIC 
then matches any portion of the specified topic. 


If you type HELP with no parameters, VAX BASIC displays a list of 
statements, functions, compiler directives, compiler commands and 
language topics. 

If the unq-str you specify is not a unique topic or subtopic, VAX BASIC 
displays information on all topics or subtopics beginning with unq-str. 


An asterisk (*) indicates that you want to display information that 
matches any portion of the topic you specify. For example, if you 
type HELP GO*, VAX BASIC displays information on the GOSUB 
statement and the GOTO statement. 
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HELP 


4. When information on a particular topic or subtopic is not available, 
VAX BASIC signals the message “Sorry, no documentation on unq-str’ 
and provides a list of alternative HELP topics to choose from. 


Ready 
Help GO* 
GOSUB 


The GOSUB statement transfers control to a specified line number or 
label and stores the location of the GOSUB statement for eventual 
return from the subroutine. 


Example 
200 GOSUB 1100 
Additional information available: 
Syntax 
GOTO 


The GOTO statement transfers control to a specified line number or 
label. 


Example 

20 GOTO 200 

Additional information available: 
Syntax 


Topic? 
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IDENTIFY 


IDENTIFY 


The IDENTIFY command displays an identification header on the control- 
ling terminal. The header contains the name and version number of VAX 


BASIC. 
Format 
IDENTIFY 
Syntax Rules 
( 
None. 
Remarks 
The message displayed by the IDENTIFY command includes the name of 
the VAX BASIC compiler and the version number. 
Example 


IDENTIFY 
VAX BASIC V3.0 
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INQUIRE 


The INQUIRE command is a synonym for the HELP command. See the 
HELP command for more information. 


2-30 BASIC Environment Commands 


LIST and LISTNH 


LIST and LISTNH 


The LIST command displays the program lines of the program currently in 
memory. Line numbers are sequenced in ascending order. The LISTNH 
command displays program lines without the program header. 


Format 
LIST[NH] tema (na | - 
,line-num... 


Syntax Rules 


A line-num followed by a hyphen (-) and a carriage return displays the 
specified line and all remaining lines in the program. 


Remarks 


1. The LIST command displays program lines, along with a header 
containing the program name, the current time, and the date. To 
suppress the program header, type LISTNH. 


2. LIST without parameters displays the entire program. 


The separator characters (comma or hyphen) allow you to display 
individual lines or a block of lines. 


e If you separate line numbers with commas, VAX BASIC displays 
each specified line number. 


¢ If you separate line numbers with hyphens, VAX BASIC displays 
the inclusive range of lines. The lower line number must come 
first. If it does not, LIST has no effect. 
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LIST and LISTNH 


4, You can combine individual line numbers and line ranges in a single 
LIST command. Note, however, that a line number range must be 
followed by a comma and not another hyphen, or VAX BASIC signals 
an error. 


5. A hyphen between the list command and line-num causes VAX BASIC 
to signal an error. 


6. VAX BASIC displays the source program lines in the order you specify 
in the command line. VAX BASIC displays line 100 before line 10 if 
you type LIST 100,10. 


Example 


LIST 200-300 


Output 


200 %IF “VARIANT = 2 %THEN %ABORT 
300 %END 4IF 
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LOAD 


LOAD 


The LOAD command makes a previously created object module or mod- 
ules available for execution with the RUN command. 


Format 


LOAD _file-spec [ + file-spec |... 
Syntax Rules 


File-spec must be a VAX BASIC object module or VAX BASIC signals an 
error. OBJ is the default file type. If you specify only the file name, VAX 
BASIC searches for an OBJ file in the current default directory. 


Remarks 


1. Each device and directory specification applies to all following file 
specifications until you specify a new directory or device. 


2. The LOAD command accepts multiple device, directory, and file 
specifications. 


3. VAX BASIC does not process the loaded object files until you issue the 
RUN command. Consequently, errors in the loaded modules may not 
be detected until you execute them. 


4. VAX BASIC signals an error in the following cases: 
e If the file is not found 
e If the file specification is not valid 
e If the file is not a VAX BASIC object module 
e If run-time memory is exceeded 


Errors do not change the program currently in memory. 
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LOAD 


5. The LOAD command clears all previously loaded object modules from 
memory. 


6. Typing the LOAD command does not change the program currently 
in memory. 


Example 


LOAD PROGA + PROGB + PROGC 
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LOCK 


LOCK 


The LOCK command changes default values for COMPILE command 
qualifiers. It is a synonym for the SET command. See the SET command 
for more information. 
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NEW 


NEW 


The NEW command clears VAX BASIC memory and allows you to assign 
a name to a new program. 


Format 


NEW | prog-name ] 
Syntax Rules 


Prog-name is the name of the program you want to create. VAX BASIC 
allows program names to contain a maximum of 39 characters. You can 
use any combination of alphanumeric characters in your program name, 
as well as the dollar sign ($), hyphen (—), and underscore (_) characters. 


Remarks 


1. VAX BASIC signals an error if prog-name exceeds 39 characters. 
2. VAX BASIC signals “error in program name” if you specify a file type. 
3. If you do not specify a prog-name, VAX BASIC prompts with: 


New file name-- 


4. The default name is NONAME. If you do not provide a prog-name in 
response to the prompt, VAX BASIC assigns the file name NONAME 
to your program. 

5. When you type the NEW command, the program currently in memory 
is cleared. Program modules loaded with the LOAD command remain 
unchanged. 
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Example 


NEW PROG1 


BASIC Environment Commands 2-37 


OLD 


OLD 


The OLD command brings a previously created VAX BASIC program into 
memory. 


Format 
OLD / file-spec ] 


Syntax Rules 


1. If you do not name a file-spec, VAX BASIC prompts for one. If you do 
not enter a file-spec in response to the prompt, VAX BASIC searches 
for a file named NONAME.BAS in the current default directory. 


2. The default file type is BAS. 


Remarks 

1. If the VAX BASIC compiler cannot find the file you specify, VAX 
BASIC signals the error “File not found”. 

2. When the specified file is found, it is placed in memory and any 
program currently in memory is erased. If VAX BASIC does not find 
the specified file, the program currently in memory does not change. 

Example 
OLD CHECK 
Ready 
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RENAME 


RENAME 


The RENAME command allows you to assign a new name to the program 
currently in memory. VAX BASIC does not write the renamed program to 
a file until you save the program with the REPLACE or SAVE command. 


Format 
RENAME / prog-name ] 


Syntax Rules 


1. Prog-name specifies the new program name. VAX BASIC allows 
program names to contain a maximum of 39 characters. You can 
use any combination of alphanumeric characters in your program 
name, as well as the dollar sign ($), hyphen (—), and underscore (—_) 
characters. 


2. If you specify a file type, VAX BASIC signals the error “Error in 
program name.” 


Remarks 


1. The program you want to rename must be in memory. If you type 
RENAME with no program in memory, VAX BASIC renames the 
default program, NONAME, to the specified prog-name. 

2. If you do not specify a prog-name, VAX BASIC renames the program 
currently in memory NONAME. 

3. You must type SAVE or REPLACE to write the renamed program to a 
file. If you do not type SAVE or REPLACE, VAX BASIC does not save 
the renamed program. 

4. The RENAME command does not affect the original saved version of 
the program. 
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RENAME 


Example 


OLD TEST 
Ready 


RENAME NEWTEST 
Ready 


LIST 
NEWTEST 29-JUL-1985 13:50 
PRINT "This program is a simple test" 


Ready 


SAVE 

“4BASIC-I-FILEWRITE, NEWTEST written to file: 
USER$$DISK : [SMITH.COMS] NEWTEST . BAS; 5 

Ready 


In this example, the OLD command calls the program named TEST into 
memory. The RENAME command renames TEST to NEWTEST and 
the SAVE command writes NEWTEST.BAS to a file. The original file, 
TEST.BAS is not changed and is not deleted from your account. 
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REPLACE 


REPLACE 


The REPLACE command writes the current program back to the file 
specified by the last OLD command. 


Format 
REPLACE 


Syntax Rules 
None. 
Remarks 


1. If you do not have write access to the directory containing the original 
. file, VAX BASIC signals an error message. 

2. VAX BASIC creates and saves a new version of the file, incrementing 
the version number by 1 unless you supplied a specific version. 
number with the OLD command. 

3. A REPLACE command following a NEW command or a SCRATCH 
command causes VAX BASIC to write the program in memory to the 
current default directory. 

4. A REPLACE command following a RENAME command writes the 
file to the directory specified in the OLD command with the file name 
specified in the RENAME command. 
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REPLACE 


¢ DIR NODE: : USER$$DISK: [BASICUSER] TEST .BAS 


Directory USER$$DISK: [BASICUSER] 
TEST.BAS;1 


Total of 1 file. 
¢ BASIC 


VAX BASIC V3.0 


Ready 
OLD NODE: : USER$$DISK: [BASICUSER] TEST . BAS ; 


Ready 
REPLACE 


4BASIC-I-FILEWRITE, TEST written to file: 
USER$$DISK : [BASICUSER] TEST . BAS ; 2 


Ready 
EXIT 


$¢ DIR NODE: :USER$$DISK : [BASICUSER] TEST . BAS 
Directory USER$$DISK : [BASICUSER] 
TEST.BAS;1 TEST.BAS;2 


Total of 2 files. 
$ 
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RESEQUENCE 


RESEQUENCE 


In a program with line numbers, the RESEQUENCE command allows 
you to resequence the line numbers of the program currently in memory. 
VAX BASIC also changes all references to the old line numbers so they 
reference the new line numbers. 


Format 
RESEQUENCE 
Syntax Rules 
1: 
2; 
3. 
4. 


[ line-num1 [ - line-num2 ] [ line-num3 ] ] [ STEP int-const ] 


Line-num1 is the line number in the program currently in memory 
where resequencing begins. The default for line-num1 is the first line 
of the program module. 


Line-num2 is the optional end of the range of line numbers to be 
resequenced. If you specify a range, VAX BASIC begins resequencing 
with line-num1 and resequences through line-num2. If you do not 
specify line-num2, VAX BASIC resequences the specified line. If you 
do not specify either line-num1 or line-num2, VAX BASIC resequences 
the entire program. 


Line-num3 specifies the new first line number; the default number 
for the new first line is 100. You can specify line-num3 only when 
resequencing a range of lines. 


If line-num3 causes existing lines to be deleted or surrounded, VAX 
BASIC signals an error. 


Int-const specifies the numbering increment for the resequencing 
operation. The default for int-const is 10. 
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RESEQUENCE 


Remarks 


1. You cannot specify the RESEQUENCE command on programs that do 
not contain line numbers. 


2. VAX BASIC signals an error when you try to resequence a program 
that contains a %IF directive. VAX BASIC also signals an error when 
you try to resequence a program that has a %INCLUDE directive if 
the file to be included contains a reference to a line number. 


3. Before the RESEQUENCE command executes, VAX BASIC verifies the 
syntax of the program. If the program is not syntactically valid, the 
RESEQUENCE command does not execute. 


4. VAX BASIC sorts the renumbered program in ascending order when 
the RESEQUENCE command executes. 


5. If the renumbering creates a line number greater than the maximum 
line number of 32767, VAX BASIC signals an error. 


6. VAX BASIC signals an error if resequencing causes a change in the 
order in which program statements are to execute and does not 
resequence the program. 


7. VAX BASIC signals the error “Undefined line number” in the case of 
undefined line numbers and does not resequence the program. 


8. VAX BASIC corrects all line numbers for statements that transfer 
- control. 


9. VAX BASIC does not modify the program currently in memory when 
the RESEQUENCE command generates an error. 


10. In general, the RESEQUENCE command is not recommended for pro- 
grams containing error handlers that test the value of ERL. However, 
the RESEQUENCE command correctly modifies the program if the 
tests that reference ERL are of this form: 


ERL relational-operator int-lit 


The RESEQUENCE command does not correctly renumber programs 
if the test compares ERL with an expression or a variable, or if ERL 
follows the relational operator. The following line number references, 
for example, would not be correctly renumbered: 


IF ERL = 1000 + A% THEN ... 
IF 1000 > ERL THEN ... 
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RESEQUENCE 


10 INPUT "Enter a numeric value"; A% 
20 IF A% = 20 

30 THEN PRINT "Bye" 

40 GOTO done 

50 ELSE GOTO 10 

60 END IF 


Output 


15 INPUT "Enter a numeric value";A% 
25 IF A% = 20 
35 ‘THEN PRINT "Bye" 


45 GOTO done 
55 ELSE GOTO 10 
65 END IF 


In this example, the command RESEQUENCE 10-60 STEP 5 causes VAX 
BASIC to resequence lines 10 through 60, incrementing each new line 
number by 5. 
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The RUN command allows you to execute a program from the BASIC 
environment without first invoking the VAX/VMS Linker to construct an 
executable image. In addition, the RUN command allows you to access 
user specified and system shareable image libraries for undefined symbols. 


Format 
RUN([NH] / file-spec ] 


Syntax Rules 
None. 
Remarks 


1. Executing a Program 


e If you specify only the file name, VAX BASIC searches for a file 
with a BAS file type in the current default directory. 


e If you do not supply a file-spec, VAX BASIC executes the program 
currently in memory. 


e VAX BASIC signals the warning message “No main program” if 
you do not supply a file-spec and do not have a program currently 
in memory. 

e The RUNNH command is identical to RUN, except that it does 
not display the program header, current date, and time. 

e When you specify a file-spec with the RUN command, VAX BASIC 
brings the program into memory and then executes it. You do not 
have to bring a program into memory with the OLD command in 
order to run it. The RUN command executes just as if the program 
had been brought into memory with the OLD command. 
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e If your program calls a subprogram, the subprogram must be 
compiled and placed in memory with the LOAD command. 
If your program tries to call a subprogram that has not been 
compiled and loaded, VAX BASIC signals an error. 


e The RUN command does not create an object module file or a list 
file. 
¢ When VAX BASIC encounters a STOP statement in the program, 


the program stops executing and control passes to the BASIC 
environment immediate mode. 


e Any VAX BASIC statement that does not require the creation 
of new storage can be entered in immediate mode to debug the 
program. You cannot create new variables in immediate mode. 


¢ Type the CONTINUE command to resume program execution. 


¢ The RUN command uses whatever qualifiers have been set, with 
the exception of those that have no effect on a program running 
in the BASIC environment. These qualifiers are as follows: 


— NOCROSS 
— NODEBUG 
— NOLIST 
— NOMACHINE 
— NOOBJECT 
These qualifiers are always in effect when you run a program in 
the environment. 
Accessing Shareable Images 
¢ To automatically access shareable image libraries, you must make 
an assignment to the logical name BASIC$LIBn. For example: 
$ ASSIGN DBAO: [BABCOCK] TESTLIB.OLB BASIC$LIBO 


e After you enter a command line, VAX BASIC will automatically 
access your library to resolve undefined program symbols. 

¢ If you have more than one library for the VAX/VMS Linker to 
search, you must assign the first one as BASIC$LIBO, the second 
one as BASIC$LIB1, the third as BASIC$LIB2, and so on. 


e If you do not number libraries consecutively, the VAX/VMS 
Linker does not search past the first missing logical name. 


e As long as routines are contained in shareable images in libraries, 
they are not required to be written in VAX BASIC to be accessed 
with the RUN command. 
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e VAX BASIC provides no default file specification for user-supplied 
shareable image libraries; the current default device and the 
directory are used. . 


e After all possible shareable image libraries have been ac- 
cessed, VAX BASIC will subsequently search the default library 
SYS$LIBRARY:.OLB with the logical name IMAGELIB to resolve 
any additional undefined program symbols. 


Example 


RUN PROG1 
PROG1 29-JUL-1986 13:52 


1 

3 

6 

10 
Ready 


RUNNH PROG1 
1 

3 

6 

10 
Ready 
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SAVE 


SAVE 


The SAVE command writes the VAX BASIC source program currently in 
memory to a file on the default or specified device. 


Format 
SAVE [ file-spec ] 


Syntax Rules 
None. 
Remarks 


1. If you do not supply a file-spec, VAX BASIC saves the file with the 
name of the program currently in memory and the BAS default file 


type. 
2. If you specify only the file name, VAX BASIC saves the program with 
the default file type in the current default directory. _ 


3. When you type the SAVE command, VAX BASIC writes a new version 
of the program. 


4. VAX BASIC stores the sorted program in ascending line number order. 
5. You can store the program on a specified device. For example: 


SAVE DUA1:NEWTEST. PRO | 
VAX BASIC saves the file NEWTEST.PRO on disk DUAI1:. 
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SAVE 


SAVE PROG_SAMP .BAS 


“%BASIC-I-FILEWRITE, PROG_SAMP written to file: 
USER$$DISK [BASICUSER] PROG_SAMP .BAS ; 2 
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SCALE 


SCALE 


The SCALE command allows you to control accumulated round-off errors 
by multiplying numeric values by 10 raised to the scale factor before 
storing them. 


Format 
SCALE = int-const 


Syntax Rules 


Int-const specifies the power of 10 you want to use as the scaling factor. 
Int-const must be an integer from 0 through 6 or VAX BASIC signals the 
error “Illegal argument for command”. 


Remarks 


1. SCALE with no argument causes VAX BASIC t to signal the error 
“Illegal argument for command”. 


2. SCALE affects only values of the data type DOUBLE. 


3. VAX BASIC multiplies values using the scale factor you specify. The 
value 2.488888, for example, is rounded as follows: 


Scale Value Produced for 2.488888 


0 2.48889 
1 2.4 

2 2.48 

3 2.488 

4 2.4888 
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SCALE 


Scale - Value Produced for 2.488888 


5 2.48888 

6 2.48889 
Example 

SCALE 2 
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SCRATCH 


SCRATCH 


The SCRATCH command clears any program currently in memory, 
removes any object files loaded with the LOAD command, and resets the 
program name to NONAME. 


Format 
SCRATCH 


Syntax Rules 
None. 
Remarks 
None. 
Example 


SCRATCH 
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SEQUENCE 


SEQUENCE 


The SEQUENCE command causes VAX BASIC to automatically generate 
line numbers for your program text. VAX BASIC supplies line numbers for 
your text until you end the procedure or reach the maximum line number 
of 32767. 


Format 
SEQUENCE [ line-num ] [ , int-const ] 


Syntax Rules 


1. Line-num specifies the line number where sequencing begins. 


2. Int-const specifies the line number increment for your program. If 
you do not specify an increment, VAX BASIC defaults to the int-const 
specified in the last SEQUENCE command; if there is no previous 
SEQUENCE command, the default is 10. 


Remarks 


1. You cannot specify the SEQUENCE command on programs that do 
not contain line numbers. 


2. If you do not specify a line-num, the VAX BASIC default is the last 
line inserted by a SEQUENCE command; if there is no previous 
SEQUENCE command, the default is line number 100. 


3. If you specify a line-num that already contains a statement, or if the 
sequencing operation generates a line number that already contains 
a statement, VAX BASIC signals “Attempt to sequence over existing 
statement”, and returns to normal input mode. 


4. Type your program text in response to the line number prompt; the 
carriage return ends each line and causes VAX BASIC to generate a 
new line number. 
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SEQUENCE 


5. If you press CTRL/Z in response to the line number prompt, VAX 
BASIC terminates the sequencing operation and prompts for another 
command. 


6. When the maximum line number of 32767 is reached, VAX BASIC 
terminates the sequencing process and returns to normal input mode. 


7. VAX BASIC does not check syntax during the sequencing process. 


SEQUENCE 100,10 
100 INPUT "Enter a numeric value"; A% 
110 IF A% = 20 


Here, if you enter the command SEQUENCE 100,10, the SEQUENCE 
command causes VAX BASIC to automatically generate line numbers into 
the program text, beginning with the line number 100 and incrementing 
each line by 10. 
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SET 





SET 


The SET command allows you to specify VAX BASIC defaults for all VAX 
BASIC qualifiers. Qualifiers control the compilation process and the run- 
time environment. The defaults you set remain in effect for all subsequent 
operations until they are reset or until you exit from the compiler. 


Format 
SET [ /qualifier J... 


Syntax Rules 


1. /Qualifier specifies a qualifier keyword that sets a VAX BASIC default. 
See the COMPILE command for a list of all VAX BASIC qualifiers and 
their defaults. 


2. VAX BASIC signals the error “Unknown qualifier” if you do not 
separate multiple qualifiers with commas (,) or slashes (/), or if you 
mix commas and slashes on the same command line. The same error 
is signaled if you separate qualifiers with a slash but do not prefix the 
first qualifier with a slash. 


Remarks 


If you do not specify any qualifiers, VAX BASIC resets all defaults to the 
defaults specified with the DCL command BASIC. 
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SET 
Examples 


Example 1 
SET /DOUBLE/BYTE/LIST 


Example 2 
SET DOUBLE, BYTE,LIST 


In both examples, the VAX BASIC compiler is set to allocate 64 bits of 
storage for all floating-point data, and to allocate 8 bits of storage for all 
integer data. Also, a source listing file is created. 
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SHOW 





SHOW 


The SHOW command displays the current defaults for the VAX BASIC 


compiler on your terminal. 


Format 
SHOW 


Syntax Rules 


None. 
Remarks 

None. ; 
Example 

SHOW 

VAX BASIC 3.0 Current Environment 


DEFAULT DATA TYPE INFORMATION: 
Data type : REAL 
Real size : SINGLE 
Integer size : LONG 
Decimal size : (15,2) 
Scale factor : 0 
NO Round decimal numbers 


COMPILATION QUALIFIERS IN EFFECT: 
Object file 

RS: Overflow check integers 
Overflow check decimal numbers 
Bounds checking 
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Status 30-OCT-1986 10:05:56.57 
LISTING FILE INFORMATION INCLUDES: 
NO List 
NO Cross reference 
CDD Definitions 
Environment 
NO Override of %NOLIST 
NO Machine code 
Map 


INCLUDE files 


FLAGGE 
NO Declining features 
NO BASIC PLUS 2 subset 


NO Syntax checking 


Lines 

Variant : 0 DEBUG INFORMATION: 
Warnings Traceback records 
Informationals NO Debug symbol records 
Setup 

Object Libraries : NONE 


Ready 
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UNSAVE 


UNSAVE 


The UNSAVE command deletes a specified file from storage. 


Format 
UNSAVE / file-spec ] 


Syntax Rules 
None. 
Remarks 


1. If you do not supply a file-spec, VAX BASIC deletes a file that has the 
file name of the program currently in memory and a file type of BAS. 


2. If you do not supply a file-spec and do not have a program in memory, 
VAX BASIC searches for the default file NONAME.BAS. 


3. If you do not specify a complete file name with a file type, VAX BASIC 
deletes the file with the specified name and the BAS file type from the 
default device and directory. Other file types with the same file name 
are not deleted. 


UNSAVE DB2:CHECK . DAT 
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Chapter 3 
Compiler Directives 


Compiler directives are instructions that cause VAX BASIC to perform cer- 
tain operations as it translates the source program. This chapter describes 
all of the compiler directives supported by VAX BASIC. The directives are 
listed and discussed alphabetically. 
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%ABORT 


%ABORT 


The %ABORT directive terminates program compilation and displays a 
fatal error message that you can supply. 


Format 
%ABORT [| str-lit ] 


Syntax Rules 
None. 
Remarks 


1. Only a line number or a comment field can appear on the same 
physical line as the % ABORT directive. 


2. VAX BASIC stops the compilation and terminates the listing file as 
soon as it encounters a % ABORT directive. An optional str-lit is 
displayed on the terminal screen and in the compilation listing, if a 
listing has been requested. 


“IF “VARIANT = 2 %THEN 
“ABORT "Cannot compile with variant 2" 
ZEND %IF 


3-2 Compiler Directives 


*%CROSS 


%*CROSS 


The %CROSS directive causes VAX BASIC to begin or resume accumulat- 
ing cross-reference information for the listing file. 


Format 
%*CROSS 
Syntax Rules 
None. 
Remarks 

1. Only a line number or a comment field can appear on the same 
physical line as the % CROSS directive. 

2. The %CROSS directive has no effect unless you request both a listing 
file and a cross-reference. For more information on listing file format, 
see the VAX BASIC User Manual. 

3. When a cross-reference is requested, the VAX BASIC compiler starts or 
resumes accumulating cross-reference information immediately after 
encountering the %CROSS directive. 

Example 


4CROSS 
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*%DECLARED 


%*DECLARED 


The %DECLARED directive is a built-in lexical function that allows you 
to determine whether a lexical variable has been defined with the %LET 
directive. If the lexical variable named in the %DECLARED function is 
defined in a previous %LET directive, the %DECLARED function returns 
the value —1. If the lexical variable is not defined in a previous %LET 
directive, the %DECLARED function returns the value 0. 


Format 
%DECLARED —_(lex-var) 


Syntax Rules 


1. The %DECLARED function can appear only in a lexical expression. 


The lex-var is the name of a lexical variable. Lexical variables are 
always LONG integers. 


3. Lex-var must be enclosed in parentheses. 
Remarks 


None. 
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I+ 

! Use the following code in {INCLUDE files 
! 

'- 

“IF ZDECLARED (%,TRUE_FALSE_DEFINED) = 0 


“THEN 
DECLARE LONG CONSTANT True = -1, False = 0 
%LET %TRUE_FALSE_DEFINED = -1 


“END “IF 


which reference constants that may be already defined. 


%DECLARED 
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*IDENT 


%*IDENT 


The %IDENT directive lets you identify the version of a program module. 
The identification text is placed in the object module and printed in the 
listing header. 


Format 


%IDENT © str-lit 
Syntax Rules 


Str-lit is the identification text. Str-lit can consist of up to 31 ASCII 
characters. If it has more than 31 characters, VAX BASIC truncates the 
extra characters and signals a warning message. 


Remarks 


1. Only a line number or a comment field can appear on the same 
physical line as the %IDENT directive. 


2. The VAX BASIC compiler inserts the identification text in the first 
31 character positions of the second line on each listing page. VAX 
BASIC also includes the identification text in the object module, if 
the compilation produces one, and in the map file created by the 
VAX/VMS Linker. 


3. The %IDENT directive should appear at the beginning of your pro- 
gram if you want the identification text to appear on the first page of 
your listing. If the %IDENT directive appears after the first program 
statement, the text will appear on the next page of the listing file. 
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%IDENT 


4. You can use the %IDENT directive only once in a module. If you 
specify more than one %IDENT directive in a module, VAX BASIC 
signals a warning and uses the identification text specified in the first 
directive. 


5. No default identification text is provided. 


%IDENT "Version 10" 


Output 


TIME$MAIN 
Version 10 


1 10 “IDENT "Version 10" 
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%IF-4oTHEN-%ELSE-%END “IF 


%IF-“%THEN-%ELSE-%END “IF 


The %IF-%THEN-%ELSE-%END %IF directive lets you conditionally 
include source code or execute another compiler directive. 


Format 
%IF  /ex-exp %THEN code [ %ELSE code ] %END %IF 


Syntax Rules 


1. Lex-exp is always a LONG integer. 

2. Lex-exp can be: 
e A lexical constant named in a %LET directive. 
e An integer literal, with or without the percent sign suffix. 
eA lexical built-in function. 


e Any combination of the above, separated by valid lexical opera- 
tors. Lexical operators include logical operators, relational opera- 
tors, and the arithmetic operators for addition (+), subtraction (-), 
multiplication (*), and division (/). 

3. Code is VAX BASIC program code. It can be any VAX BASIC state- 
ment or another compiler directive, including another %IF directive. 

You can nest %IF directives to eight levels. 
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temarks 


%IF-“THEN-%ELSE-%END “IF 


The %IF directive can appear anywhere in a program where a space is 
allowed, except within a quoted string. This means that you can use 
the %IF directive to make a whole statement, part of a statement, or a 
block of statements conditional. 


%THEN, %ELSE, and %END %IF do not have to be on the same 
physical line as %IF. 


If lex-exp is true, VAX BASIC processes the %THEN clause. If lex- 
exp is false, VAX BASIC processes the %ELSE clause. If there is no 
%ELSE clause, VAX BASIC processes the %END %IF clause. The 
VAX BASIC compiler includes statements in the %THEN or %ELSE 
clause in the source program and executes directives in order of 
occurrence. 

You must include the %END %IF clause. Otherwise, VAX BASIC 
assumes the remainder of the program is part of the last % THEN 
or %ELSE clause and signals the error “MISENDIF, missing END IF 
directive” when compilation ends. 


%IF (%VARIANT = 2) 

%THEN DECLARE SINGLE hourly_pay (100) 

“ZELSE ZIF CAVARIANT = 1) 
%THEN DECLARE DOUBLE salary_pay(100) 
%ELSE %ABORT "Can't compile with specified variant" 
%END %IF 

%END %IF 


PRINT ZIF (AVARIANT = 2) 
“THEN ‘Hourly Wage Chart' 
GOTO Hourly_routine 
Y%ELSE 'Salaried Wage Chart' 
GOTO Salary_routine 
%END %IF 
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%INCLUDE 


*INCLUDE 


The %INCLUDE directive lets you include VAX BASIC source text from 
another program file in the current program compilation. VAX BASIC also 
lets you access record definitions in the VAX Common Data Dictionary 
(CDD) and access commonly used routines from text libraries. 


Format 


Including a File 


%INCLUDE © str-lit 


Including a CDD Definition 
%INCLUDE %FROM %CDD str-lit 


Including a File from a Text Library 


%INCLUDE © str-lit S%FROM %LIBRARY [str-/it] 
Syntax Rules 


1. Including a File 


Str-lit must be a valid file specification for the file to be included. 
2. Including a CDD Definition 
Str-lit specifies a VAX CDD path name enclosed in quotation marks. 


The path name can be in either DMU or CDO format. This directive 
lets you extract a RECORD definition from the dictionary. 


3. Including a File from a Text Library 
e  Str-lit specifies a particular module to be included. 


e The optional str-lit identifies a specific text library in which the 
included module resides. If the library name is not specified, VAX 
BASIC uses the default library name BASIC$LIBRARY. 
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Remarks 


%INCLUDE 


Any statement that appears after an END statement inside an included 
file causes VAX BASIC to signal an error. 


Only a line number or a comment field can appear on the same 
physical line as the %INCLUDE directive. 


The VAX BASIC compiler includes the specified source file in the 
program compilation at the point of the %INCLUDE directive and 
prints the included code in the program listing file if the compilation 
produces one. 


The included file cannot contain line numbers. If it does, VAX BASIC 
signals the error “Line number may not appear in %INCLUDE file”. 


All statements in the accessed file are associated with the line number 
of the program line that contains the %INCLUDE directive. This 
means that a %INCLUDE directive cannot appear before the first line 
number in a source program if you are using line numbers. 


A file accessed by %INCLUDE can itself contain a %INCLUDE 
directive. 


All %IF directives in an included file must have a matching %END 
%IF directive in the file. 


You can control whether or not included text appears in the compila- 
tion listing with the /[NO]JSHOW:INCLUDE qualifier to the COMPILE 
command. When you specify /SHOW:INCLUDE, the compilation 
listing file identifies any text obtained from an included file by placing 
a mnemonic in the first character position of the line on which the 
text appears. The “n” specifies that the text was either accessed from 
a source file or from a text library. The “I” tells you that the text was 
accessed with the %INCLUDE directive and n is a number that tells 
you the nesting level of the included text. See the VAX BASIC User 
Manual for more information on listing mnemonics. 


Including a File 


If you do not specify a complete file specification, VAX BASIC uses the 
default device and directory and the file type BAS. 


10. Including a CDD Definition 


e In versions prior to VAX CDD/Plus Version 4.0, there are two 
types of CDD path names: full and relative. A full path name be- 
gins with CDD$TOP and specifies the complete path to the record 
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*INCLUDE 
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definition. A relative path name begins with any string other than 
CDD$TOP and is appended to the current CDD$DEFAULT. 


In VAX CDD/Plus Version 4.0 or higher, the pathnames described 
previously are known as DMU pathnames, as distinct from CDO 
pathnames. You can specify either a full DMU pathname, a full 
CDO pathname, or a relative pathname. A full pathname consists 
of a dictionary origin followed by a dictionary path. A full DMU 
pathname has CDD$TOP as its origin. A full CDO pathname has 
an anchor as its origin. See CDD/Plus documentation for detailed 
information on pathnames. 


If the record definition being accessed is in a CDO-format dictio- 
nary, you can create a dependency relationship in the dictionary 
between a dictionary representation of your program and the 
record definitions that you include in the program. The dictionary 
representation of the program is called a compiled module entity. 


If you specify the /DEPENDENCY_DATA qualifier to the com- 
piler and your CDD$DEFAULT points to a CDO-format dictio- 
nary, a compiled module entity is created for each compilation 

unit at compile time in CDD$DEFAULT. No compiled module 

entity is created if both conditions are not true. 


If a compiled module entity exists for the program, an %INCLUDE 
%FROM %CDD directive specifying a record description in 

a CDO-format dictionary creates a relationship between the 
compiled module entity and the CDO-format record definition. 


If the record description specified in the pathname exists, it is 
copied to the program, whether a compiled module entity can be 
created or not. 


When you use the %INCLUDE directive to extract a record defini- 
tion from the CDD, VAX BASIC translates the CDD definition to 
the syntax of the VAX BASIC RECORD statement. 

You can use the /SHOW:CDD_DEFINITIONS qualifier to specify 
that translated CDD definitions (in RECORD statement syntax) are 
included in the compilation listing file. VAX BASIC places a “C” 
in column 1 when the translated RECORD statement appears in 
the listing file. 

When you specify /SHOW:NOCDD_DEFINITIONS, VAX BASIC 
does not include the CDD definition in the listing file. However, 
VAX BASIC still includes the names, data types, and offsets of the 
CDD record components in the program listing’s allocation map. 
See the VAX BASIC User Manual and the CDD/Plus documenta- 
tion for more information on dictionary data definitions. 
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%INCLUDE 


11. Including a File from a Text Library 


e The VAX BASIC compiler searches through the specified text 
library for the module named and compiles the module upon 
encountering the %INCLUDE directive. 

e VAX BASIC allows only 16 text libraries to be opened at one 
time. Therefore, you cannot have %INCLUDE directives from a 
text library nested more than 16 levels deep. If you exceed this 
maximum, VAX BASIC signals an error message. 

e If you do not specify a directory name and file type, VAX BASIC 
uses the default device and directory and the file type TLB. 

e VAX BASIC provides the text library BASIC$STARLET. 
BASIC$STARLET contains condition codes and other symbols 
defined in the system object and shareable image libraries. Using 
the definitions from BASIC$STARLET allows you to reference 
condition codes and other system-defined symbols as local, rather 


than global symbols. To create your own text libraries using the 
VAX/VMS Librarian Utility, see the VMS Librarian Utility Manual. 


Example 1 


!Including a File 
Z%INCLUDE "YESNO" 


Example 2 


‘Including a CDD Definition 
“INCLUDE %FROM %CDD "CDD$TOP . EMPLOYEE" 


Example 3 
'Including a CDD Definition with a CDO-format pathname 


%INCLUDE %FROM %CDD "MYNODE: :MY$DISK: [MY_DIR] PERSONNEL. EMPLOYEE" 
'The anchor is MYNODE: :MY$DISK: [MY_DIR] 


Example 4 


{Including a File from a Text Library 
Z%INCLUDE "EOF_CHECK" %FROM %LIBRARY "SYS$LIBRARY :BASIC_LIB.TLB" 
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%LET 


%LET 


The %LET directive declares and provides values for lexical variables. 
You can use lexical variables only in conditional expressions in the %IF- 
%THEN-%ELSE directive and in lexical expressions in subsequent %LET 
directives. 


Format 


%LET  %lex-var = lex-exp 


Syntax Rules 


1. Lex-var is the name of a lexical variable. Lexical variables are always 
LONG integers. 

2. Lex-var must be preceded by a percent sign (%) and cannot end with 
a dollar sign ($) or percent sign. 


3. Lex-exp can be any of the following: 
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A lexical variable named in a previous %LET directive. 
An integer literal, with or without the percent sign suffix. 
A lexical built-in function. 


Any combination of the above, separated by valid lexical opera- 
tors. Lexical operators can be logical operators, relational opera- 
tors, and the arithmetic operators for addition (+), subtraction (-), 
multiplication (*), and division (/). 


%LET 


Remarks 

1. Only a line number or a comment field can appear on the same 
physical line as the %LET directive. 

2. You cannot change the value of lex-var within a program unit once it 
has been named in a %LET directive. For more information on coding 
conventions see the VAX BASIC User Manual. 

Example 


%LET %DEBUG_ON = 1% 
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*LIST 


“LIST 


The %LIST directive causes the VAX BASIC compiler to start or resume 
accumulating compilation information for the program listing file. 


Format 
*LIST 
Syntax Rules 
None. 
Remarks 
1. Only a line number or a comment field can appear on the same 
physical line as the %LIST directive. 
2. The %LIST directive has no effect unless you requested a listing file. 
For more information on listing file format, see the VAX BASIC User 
Manual. 
3. As soon as it encounters the %LIST directive, the VAX BASIC compiler 
starts or resumes accumulating information for the program listing file. 
Thus, the directive itself appears as the next line in the listing file. 
Example 


“LIST 
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%NOCROSS 


*NOCROSS 


The %NOCROSS directive causes the VAX BASIC compiler to stop 
accumulating cross-reference information for the program listing file. 


Format 
%NOCROSS 


Syntax Rules 
None. 
Remarks 


1. Only a line number or a comment field can appear on the same 
physical line as the %NOCROSS directive. 


2. The VAX BASIC compiler stops accumulating cross-reference infor- 
mation for the program listing file immediately after encountering the 
%NOCROSS directive. 


3. The %NOCROSS directive has no effect unless you request a listing 
file and cross-reference information. 


4. DIGITAL recommends that you do not embed a %NOCROSS directive 
within a statement. Embedding a %NOCROSS directive within a 
statement makes the accumulation of cross-reference information 
unpredictable. For more information on listing file format, see the 
VAX BASIC User Manual. 
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*NOCROSS 


Example 


4NOCROSS 
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%NOLIST 


%NOLIST 


The %NOLIST directive causes the VAX BASIC compiler to stop accumu- 
lating compilation information for the program listing file. 


Format 
*NOLIST 
Syntax Rules 
None. 
Remarks 

1. Only a line number or a comment field can appear on the same 
physical line as the %NOLIST directive. 

2. As soon as it encounters the %NOLIST directive, the VAX BASIC 
compiler stops accumulating information for the program listing file. 
Thus, the directive itself does not appear in the listing file. 

3. The %NOLIST directive has no effect unless you requested a listing 
file. 

4. In VAX BASIC, you can override all %NOLIST directives in a program 
with the /SHOW:OVERRIDE qualifier. For more information on 
listing file format, see the VAX BASIC User Manual. 

Example 


Y%NOLIST 
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*PAGE 


%PAGE 


The %PAGE directive causes VAX BASIC to begin a new page in the 
program listing file immediately after the line that contains the %PAGE 


directive. 
Format 
%PAGE 
Syntax Rules 
None. 
Remarks 
1. Only a line number or a comment field can appear on the same 
physical line as the %PAGE directive. 
2. The %PAGE directive has no effect unless you request a listing file. 
Example 


%PAGE 
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%PRINT 


%PRINT 


The %PRINT directive lets you insert a message into your source code 
that the VAX BASIC compiler prints during compilation. 


Format 
%PRINT © str-lit 


Syntax Rules 
None. 


Remarks 


1. Only a line number or a comment field can appear on the same 
physical line as the %PRINT directive. 


2. VAX BASIC will print the message specified as soon as it encounters 
a %PRINT directive. Str-lit is displayed on the terminal screen and in 
the compilation listing. 


%IF %DEBUG = 1% THEN 
%PRINT "This is a debug compilation" 


Output 
“%BASIC-S-USERPRINT, This is a debug compilation 
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%REPORT 


%REPORT 


The %REPORT directive lets you record a dependency relationship 
between the compiled module entity for your program and the data 
definitions in CDD/Plus dictionaries. The data definitions are not copied 
into the program. 


Format 


%REPORT “DEPENDENCY - str-lit [ relationship-type ] 
Syntax Rules 


1. str-lit specifies a path name in a CDO-format dictionary. It can be 
either a DMU-format pathname or a CDO-format pathname, enclosed 
in quotation marks. This specifies a dictionary entity, such as a form 
definition or an Rdb/VMS database, that the program references. 


2. relationship-type specifies a valid CDD/Plus protocol; it must be 


enclosed in quotation marks if specified. The default relationship-type 
is CDD$COMPILED_DEPENDS_ON. 


Remarks 


1. For this directive to be meaningful, you must specify the 
/DEPENDENCY_DATA qualifier at compile time. If /DEPENDENCY 
is not specified, the compiler will simply check syntax and otherwise 
ignore the %REPORT directive. 


2. Your current CDD$DEFAULT and str-lit must refer to CDO-format 
dictionaries (not necessarily the same one). 

3. If you specify the /DEPENDENCY_DATA qualifier to the compiler, 
and if CDD$DEFAULT points to a CDO-format dictionary, a compiled 
module entity is created in CDD$DEFAULT for each compilation unit. 
No compiled module entity is created if both conditions are not true. 
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%REPORT 


4. The %REPORT %DEPENDENCY directive creates a dependency 
relationship in the dictionary between the compiled module entity for 
the program and the CDO-format dictionary entity to which it refers. 


Example 


'Establish access to the form PINK_SLIP in a dictionary 

!'on a specified node, and report the program's dependency 
'relationship with the form. 

“REPORT “DEPENDENCY "MYNODE: :MY$DISK: [MYDIR] PERSONNEL. FORMS .PINK_SLIP" 
'Relationship is CDD$COMPILED_DEPENDS_ON, the default. 
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*SBITL 


%SBITL 


The %SBTTL directive lets you specify a subtitle for the program listing 
file. 


Format 
%SBTTL - str-lit 


Syntax Rules 
Str-lit can contain up to 45 characters. 
Remarks 


1. VAX BASIC truncates extra characters from str-lit and does not signal 
a warning or error. 


2. Only a line number or a comment field can appear on the same 
physical line as the %SBTTL directive. 


3. The specified subtitle appears underneath the title on the second line 
of all pages of source code in the listing file until the VAX BASIC 
compiler encounters another %SBTTL or %TITLE directive. VAX 
BASIC clears the subtitle field before the allocation map section of the 
listing is generated. This way, you only get a subtitle on the listing 
pages that contain source code. 


4. Because VAX BASIC associates a subtitle with a title, a new %TITLE 
directive sets the current subtitle to the null string. In this case, no 
subtitle appears in the listing until VAX BASIC encounters another 
%SBTTL directive. 


5. If you want a subtitle to appear on the first page of your listing, the 
%SBTTL directive should appear at the beginning of your program, 
immediately after the %TITLE directive. Otherwise, the subtitle will 
start to appear only on the second page of the listing. 
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%*SBTTL 


6. If you want the subtitle to appear on the page of the listing that 
contains the %SBTTL directive, the %SBTTL directive should immedi- 
ately follow a %PAGE directive or a %TITLE directive that follows a 
%PAGE directive. 


7. The %SBTTL directive has no effect unless you request a listing file. 


ZTITLE "Learning to Program in VAX BASIC" 
“%SBITL "Using FOR-NEXT Loops" 

REM THIS PROGRAM IS A SIMPLE TEST 
DATA 1, 2, 3, 4 


100 
200 
NEXT I, 
300 END 
Output 
TEST$MAIN 
4 100 
2 
3 
4 200 
10 
11 300 


Learning to Program in VAX BASIC 
Using FOR-NEXT Loops 


“TITLE "Learning to Program in VAX BASIC" 
“SBITL "Using FOR-NEXT Loops" 

REM THIS PROGRAM IS A SIMPLE TEST 

DATA 1, 2, 3, 4 


NEXT I% 
END 
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‘TITLE 


*TITLE 


The %TITLE directive lets you specify a title for the program listing file. 


Format 


%TITLE — str-lit 


Syntax Rules 


Str-lit can contain up to 45 characters. 


Remarks 


3-24 Compiler Directives 


VAX BASIC truncates extra characters from str-lit and does not signal 
a warning or error. 


Only a line number or a comment field can appear on the same 
physical line as the %TITLE directive. 

The specified title appears on the first line of every page of the listing 
file until VAX BASIC encounters another %TITLE directive in the 
program. 

The %TITLE directive should appear on the first line of your program, 
before the first statement, if you want the specified title to appear on 
the first page of your listing. 


If you want the specified title to appear on the page that contains the 
%TITLE directive, the %TITLE directive should immediately follow a 
%PAGE directive. 


Because VAX BASIC associates a subtitle with a title, a new %TITLE 
directive sets the current subtitle to the null string. 


The %TITLE directive has no effect unless you request a listing file. 


100 


200 


300 


“TITLE "Learning to Program in VAX BASIC" 
REM THIS PROGRAM IS A SIMPLE TEST 
DATA 1, 2, 3, 4 


NEXT I% 
END 


Output 
TEST$MAIN 


mwWd 


10 
11 


100 


200 


300 


%*TITLE 


Learning to Program in VAX BASIC 


“TITLE "Learning to Program in VAX BASIC" 


“%SBITL "Using FOR-NEXT Loops" 
REM THIS PROGRAM IS A SIMPLE TEST 
DATA 1, 2, 3, 4 


NEXT I% 
END 
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%VARIANT 


%VARIANT 


The %VARIANT directive is a built-in lexical function that allows you to 
conditionally control program compilation. %VARIANT returns an integer 
value when you reference it in a lexical expression. You set the variant 
value with the /VARIANT qualifier when you compile the program or 
with the SET %VARIANT command. 


Format 
%VARIANT 


Syntax Rules 
None. 
Remarks 


1. The %VARIANT function can appear only in a lexical expression. 


2. The %VARIANT function returns the integer value specified either 
with the COMPILE /VARIANT command, the SET /VARIANT 
command, or the DCL command BASIC. The returned integer always 
has a data type of LONG. 
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%*VARIANT 


Y%LET %VAX = 0 
“LET %RSX = 1 
Y%LET %RSTS = 2 


“IF YVARIANT = “VAX 
“.THEN 


“ELSE %IF %VARIANT = %RSX OR %VARIANT = %RSTS 
“4. THEN 


ZELSE %ABORT "Illegal compilation variant" 
“END %IF 


%END “IF 
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Chapter 4 
Statements and Functions 


This chapter provides reference material on all of the VAX BASIC 
statements and functions. The statements and functions are listed in 
alphabetical order and each description contains the following sections: 


Definition A description of what the statement does. 
Format The required syntax for the statement. 
Syntax Rules =. — Any rules governing the use of parameters, separators, or 


other syntax items. 


Remarks Explanatory remarks concerning the effect of the statement on 
program execution and any restrictions governing its use. 


Example One or more examples of the statement in a VAX BASIC 
program. Where appropriate, sample output is also shown. 
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ABS 


ABS 


The ABS function returns a floating-point number that equals the absolute 
value of a specified floating-point expression. 


Format 


real-var = ABS (real-exp) 
Syntax Rules 
None. 
Remarks 


1. The argument of the ABS function must be a real expression. When 
the argument is a real expression, VAX BASIC returns a value of the 
same floating-point size. When the argument is not a real expression, 
VAX BASIC converts the argument to the default floating-point size 
and returns a value of the default floating-point size. 


2. The returned floating-point value is always greater than or equal to 
zero. The absolute value of zero is zero. The absolute value of a 
positive number equals that number. The absolute value of a negative 
number equals that number multiplied by -1. 
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G = 6.1273 
A = ABS(-100 * G) 

B = -39 

PRINT ABS(B), A 
Output 

39 512.73 


ABS 
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ABS% 


The ABS% function returns an integer that equals the absolute value of a 
specified integer expression. 


Format 


int-var = ABS% (int-exp) 
Syntax Rules 
None. 
Remarks 


1. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default integer size. 


2. The returned value is always greater than or equal to zero. The 
absolute value of zero is zero. The absolute value of a positive 
number equals that number. The absolute value of a negative number 
equals that number multiplied by -1. 


Example 
G4 = 5.1273 
A = ABS%(-100% * GY) 
B = -39 


PRINT ABS4,(B), A 


Output 
39 512 
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ASCII 


ASCII 


The ASCII function returns the ASCII value in decimal of a string’s first 


character. 
Format 
int-var -| pee (str-exp) 
Syntax Rules 
None. 
Remarks 
1. The ASCII value of a null string is zero. 
2. The ASCII function returns an integer value of the default size be- 
tween 0 and 255. 
Example 


DECLARE STRING time_out 
time_out = "Friday" 
PRINT ASCII (time_out) 


Output 


70 


Statements and Functions 4-5 


ATN 


ATN 


The ATN function returns the arctangent (that is, angular value) of a 
specified tangent in radians or degrees. 


Format 


real-var = ATN (real-exp) 
Syntax Rules 
None. 


Remarks 


ATN returns a value from —PI/2 through PI/2. 


2. The returned angle is expressed in radians or degrees, depending on 
which angle clause you choose with the OPTION statement. 


3. The argument of the ATN function must be a real expression. When 
the argument is a real expression, VAX BASIC returns a value of the 
same floating-point size. When the argument is not a real expression, 
VAX BASIC converts the argument to the default floating-point size 
and returns a value of the default floating-point size. 
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ATN 


Example 


OPTION ANGLE = RADIANS 

DECLARE SINGLE angle_rad, angle_deg, T 

INPUT "Tangent value" ;T 

angle_rad = ATN(T) 

PRINT "The smallest angle with that tangent is" ;angle_rad; "radians" 
angle_deg = angle_rad/(PI/180) 

PRINT “and"; angle_deg; "degrees" 


Output 


Tangent value? 2 
The smallest angle with that tangent is 1.10715 radians 
and 63.435 degrees 
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BUFSIZ 


The BUFSIZ function returns the record buffer size, in bytes, of a specified 
channel. 


Format 
int-var = BUFSIZ (chnl-exp) 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number. 
2. The value assigned to int-var is a LONG integer. 


Remarks 


1. If the specified channel is closed, BUFSIZ returns a value of zero. 
2. BUFSIZ of channel #0 always returns the value 132. 


Example 


DECLARE LONG buffer_size 
buffer_size = BUFSIZ(0) 
PRINT "Buffer size equals"; buffer_size 


Output 


Buffer size equals 132 
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The CALL statement transfers control to a subprogram, external function, 
or other callable routine. You can pass arguments to the routine and can 
optionally specify passing mechanisms. When the called routine finishes 
executing, control returns to the calling program. 


Format 


CALL routine [ pass-mech] [ ( actual-param ,...) ] 


a sub-name 
oe { any-callable-routine 
BY VALUE 
pass-mech: BY REF 
BY DESC 
exp : 
actual-param: { an } [pass-mech] 
Syntax Rules 


1. Routine is the name of a SUB subprogram or any other callable 
procedure, such as a system service or an RTL routine you want to 
call. It cannot be a variable name. See the VAX BASIC User Manual 
for more information on using system services, RTL routines, and 
other procedures. 


2. Pass-mech specifies how arguments are passed to the called routine. 
If you do not specify a pass-mech, VAX BASIC passes arguments as 
indicated in Table 4-1. 


e BY VALUE specifies that VAX BASIC passes the argument’s 32-bit 
value. 
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e BY REF specifies that VAX BASIC passes the argument’s address. 
This is the default for all arguments except strings and entire 
arrays. 


e BY DESC specifies that VAX BASIC passes the address of a VAX 
BASIC descriptor. For information about the format of a VAX 
BASIC descriptor for strings and arrays, see Appendix C. For 
more information on other types of descriptors, see the VAX 
Architecture Handbook. 


Table 4-1: VAX BASIC Parameter-Passing Mechanisms 


BY 
Parameter VALUE BY REF BY DESC 
Integer and Real Data 
i 
Variables Yes Yes Yes 
Constants Yes Local Local 
copy! copy 
Expressions Yes Local Local 
copy! copy 
Elements of a Yes Yes! Yes 
nonvirtual array 
Virtual Yes Local Local 
array elements copy! copy 
Nonvirtual No Yes Yes! 
entire array 
Virtual No No No 
entire array 
Packed Decimal Data 
oo 
Variables No Yes Yes 
Constants No Local Local 
copy! copy 
Expressions No Local Local 
copy’ copy 
Nonvirtual No Yes! Yes 


array elements 


\ Specifies the default parameter-passing mechanism. 
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Table 4-1 (Cont.): VAX BASIC Parameter-Passing Mechanisms 


BY 
Parameter VALUE BY REF BY DESC 
Packed Decimal Data 
Virtual No Local Local 
array elements copy! copy 
Nonvirtual No Yes Yes! 
entire arrays 
Virtual No No No 
entire arrays 
String Data 
a 
Variables No Yes Yes 
Constants No Local Local 
copy copy! 
Expressions No Local Local 
copy copy! 
Nonvirtual No Yes Yes! 
array elements 
Virtual No Local Local 
array elements copy copy! 
Nonvirtual No Yes Yes! 
entire arrays 
Virtual No No No 
entire arrays 
Other Parameters 
Se IEEIIETITITEEEEEEEEEEEET< paEEEEEEEEEETEET SUE TERRE REE 
RECORD variables No Yes No 
RFA variables No Yes! No 


I Specifies the default parameter-passing mechanism. 


3. You should use parameter-passing mechanisms only when calling 
non-BASIC routines or when a subprogram expects to receive a string 
or entire array by reference. 
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Remarks 


When pass-mech appears before the parameter list, it applies to all 
arguments passed to the called routine. You can override this passing 
mechanism by specifying a pass-mech for individual arguments in the 
actual-param list. 


Actual-param lists the arguments to be passed to the called routine. 


You can pass expressions or entire arrays. Optional commas in 
parentheses after the array name specify the dimensions of the array. 
The number of commas is equal to the number of dimensions - 

1. Thus, no comma specifies a one-dimensional array, one comma 
specifies a two-dimensional array, two commas specify a three- 
dimensional array, and so on. 


You cannot pass entire virtual arrays. 


The name of the routine can be from 1 to 31 characters and must 
conform to the following rules: 


e The first character of an unquoted name must be an alphabetic 
character (A through Z). The remaining characters, if present, can 
be any combination of letters, digits (0 through 9), dollar signs 
($), periods (.), or underscores (—). 


e¢ A quoted name can consist of any combination of printable ASCII 
characters. 


VAX BASIC allows you to pass up to 255 parameters. 


You can specify a null argument as an actual-param for non-BASIC 
routines by omitting the argument and the pass-mech, but not the com- 
mas or parentheses. This forces VAX BASIC to pass a null argument 
and allows you to access system routines from VAX BASIC. 


Arguments in the actual-param list must agree in data type and 
number with the formal parameters specified in the subprogram. 


An argument is modifiable when changes to it are evident in the 
calling program. Changing a modifiable parameter in a subprogram 
means the parameter is changed for the calling program as well. 
Variables and entire arrays passed by descriptor or by reference are 
modifiable. 
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4. An argument is nonmodifiable when changes to it are not evident 
in the calling program. Changing a nonmodifiable argument in a 
subprogram does not affect the value of that argument in the calling 
program. Arguments passed by value, constants, and expressions are 
nonmodifiable. Passing an argument as an expression (by placing 
it in parentheses) changes it from a modifiable to a nonmodifiable 
argument. Virtual array elements passed as parameters are non- 
modifiable. 


5. VAX BASIC will automatically convert numeric actual parameters to 
match the declared data type. If the actual parameter is a variable, 
VAX BASIC signals the informational message “Mode for parameter 

<n> of routine <name> changed to match declaration” and 
passes the argument by local copy. This prevents the called routine 
from modifying the contents of the variable. 


6. For expressions and virtual array elements passed by reference, VAX 
BASIC makes a local copy of the value, and passes the address of this 
local copy. For dynamic string arrays, VAX BASIC passes a descriptor 
of the array of string descriptors. The compiler passes the address 
of the argument’s actual value for all other arguments passed by 
reference. 


7. Only BYTE, WORD, LONG, and SINGLE values can be passed by 


value. BYTE and WORD values passed by value are converted to 
LONG values. 


8. If you attempt to call an external function, VAX BASIC treats the 
function as if it were invoked normally and validates all parameters. 
Note that you cannot call a STRING, HFLOAT, or RFA function. See 
the EXTERNAL statement for more information on how to invoke 
functions. 


EXTERNAL SUB LIB$PUT_OUTPUT (string) 

DECLARE STRING msg_str 

msg_str = "Successful call to LIB$PUT_OUTPUT!" 
CALL LIB$PUT_OUTPUT (msg_str) 


Output 


Successful call to LIB$PUT_OUTPUT! 
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CAUSE ERROR 


The CAUSE ERROR statement allows you to artificially generate a VAX 
BASIC run-time error and transfer program control to a VAX BASIC error 
handler. 


Format 


CAUSE ERROR ss er-num 

Syntax Rules 

Err-num must be a valid VAX BASIC run-time error number. 
Remarks 

All error numbers are listed in the VAX BASIC User Manual. 
Example 

—_ ERROR IN 

CAUSE ERROR 11% 


USE 
SELECT ERR 
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CASE = 11 
PRINT "End of file" 
CONTINUE 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END WHEN 


CAUSE ERROR 
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CCPOS 


The CCPOS function returns the current character or cursor position of 
the output record on a specified channel. 


Format 
int-var = CCPOS (chni-exp) 


Syntax Rules 
Chnl-exp must specify an open file or terminal. 
Remarks 


1. If chnl-exp is zero, CCPOS returns the current character position of the 
controlling terminal. 


2. The int-var returned by the CCPOS function is of the default integer 
size. 


3. The CCPOS function counts only characters. If you use cursor ad- 
dressing sequences such as escape sequences, the value returned will 
not be the cursor position. 


4. The first character position on a line is zero. 
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CCPOS 
Example 


DECLARE LONG curs_pos 
PRINT "Hello"; 
curs_pos = CCPOS (0) 
PRINT curs_pos 


Output 


Hello 5 
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CHAIN 


The CHAIN statement transfers control from the current program to 
another executable image. CHAIN closes all files, then requests that the 
new program begin execution. Control does not return to the original 
program when the new image finishes executing. 


NOTE 


The CHAIN statement is not recommended for new program 
development. DIGITAL recommends that you use subprograms, 
external functions and pictures for program segmentation. 


Format 
CHAIN _ str-exp 


Syntax Rules 


Str-exp represents the file specification of the program to which control is 
passed. It can be a quoted or unquoted string. 


Remarks 


1. Str-exp must refer to an executable image or VAX BASIC signals an 
error. 


2. If you do not specify a file type, VAX BASIC searches for an EXE file 
type. 

3. You cannot chain to a program on another node. 

4. Execution starts at the beginning of the specified program. 


5. Before chaining takes place, all active output buffers are written, all 
open files are closed, and all storage is released. 
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6. Because a CHAIN statement passes control from the executing image, 
the values of any program variables are lost. This means that you 
can pass parameters to a chained program only by using files or a 
system-specific feature such as LIB$GET_COMMON and LIB$PUT_ 
COMMON. 


Example 


DECLARE STRING time_out 
time_out = "Friday" 
PRINT ASCII (time_out) 
CHAIN "CCPOS" 


Output 


70 
The current cursor position is 0 


In this example, control is passed from the executing image, ASCIIEXE to 
the chained program, CCPOS.EXE. The value that results from ASCIIEXE 
is 70. The second line of output reflects the value that results from 
CCPOS.EXE. 
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CHANGE 


The CHANGE statement either converts a string of characters to their 
ASCII integer values or converts a list of numbers to a string of ASCII 
characters. 


Format 


String Variable to Array 
CHANGE - str-exp TO num-array-name 


Array to String Variable 
CHANGE = num-array-name TO str-var 


Syntax Rules 


Str-exp is a string expression. 


2. Num-array-name should be a one-dimensional array. If you specify a 
two-dimensional array, VAX BASIC converts only the first row of that 
array. VAX BASIC does not support conversion to or from arrays of 
more than two dimensions. 


Remarks 


1. VAX BASIC does not support RECORD elements as a destination 
string or as a source or destination array for the CHANGE statement. 


2. String Variable to Array 


e This format converts each character in the string to its ASCII 
value. 


e VAX BASIC assigns the value of the string’s length to the first 
element of the array. 
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VAX BASIC assigns the ASCII value of the first character in the 
string to the second element, (1) or (0,1), of the array, the ASCII 
value of the second character to the third element, (2) or (0,2), 
and so on. 


If the string is longer than the bounds of the array, VAX BASIC 
does not translate the excess characters, and signals the error 
“Subscript out of range” (ERR=55). The first element of array still 
contains the length of the string. 


Array to String Variable 


This format converts the elements of the array to a string of 
characters. 


The length of the string is determined by the value in the zero 
element, (0) or (0,0), of the array. If the value of element zero 
is greater than the array bounds, VAX BASIC signals the error 
“Subscript out of range” (ERR=55). 


VAX BASIC changes the first element, (1) or (0,1), of array to its 
ASCII character equivalent, the second element, (2) or (0,2), to 
its ASCII equivalent, and so on. The length of the returned string 
is determined by the value in the zero element of the array. For 
example, if the array is dimensioned as (10), but the zero element 
(0) contains the value 5, VAX BASIC changes only elements (1), 
(2), (3), (4), and (5) to string characters. 


VAX BASIC truncates floating-point values to integers before 
converting them to characters. 


Values in array elements are treated modulo 256. 
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Example 


DECLARE STRING ABCD, A 

DIM INTEGER array_changes (6) 
ABCD = "ABCD" 

CHANGE ABCD TO array_changes 
FOR I% = 0 TO 4 

PRINT array_changes(I%) 

NEXT 1% 

CHANGE array_changes TO A 
PRINT A 


Output 
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The CHR$ function returns a 1-character string that corresponds to the 
ASCII value you specify. 


Format 


str-var = CHR$ (int-exp) 
Syntax Rules 
None. 
Remarks 


1. CHRg$ returns the character whose ASCII value equals int-exp. If 
int-exp is greater than 255, VAX BASIC treats it modulo 256. For 
example, CHR$(325) is the same as CHR$(69). 


2. All arguments between 0 and 255 are considered unsigned 8-bit 
integers. For example, -1 is treated as 255. 


3. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


DECLARE INTEGER num_exp 
INPUT "Enter the ASCII value you wish to be converted" ;num_exp 
PRINT "The equivalent character is ";CHR$(num_exp) 


Output 


Enter the ASCII value you wish to be converted? 89 
The equivalent character is Y 
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CLOSE 


The CLOSE statement ends I/O processing to a device or file on the 
specified channel. 


Format 
CLOSE /#Jchnl-exp.... 


Syntax Rules 


Chnl-exp is a numeric expression that specifies a channel number as- 
sociated with a file. It can be preceded by an optional number sign 


(#). 
Remarks 


1. VAX BASIC writes the contents of any active output buffers to the file 
or device before it closes that file or device. 


2. Channel #0 (the controlling terminal) cannot be closed. An attempt to 
do so has no effect. 


3. If you close a magnetic tape file that is open for output, VAX BASIC 
writes an end-of-file on the magnetic tape. 


4. If you try to close a channel that is not currently open, VAX BASIC 
does not signal an error and the CLOSE statement has no effect. 
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Example 


OPEN "COURSE_REC.DAT"* FOR INPUT AS #2 
INPUT #2, course_nam, course_num, course_desc, course_instr 


CLOSE #2 


In this example, COURSE_REC.DAT is opened for input. Once the user 
inputs all of the required information, the file is closed. 
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COMMON 


The COMMON statement defines a named, shared storage area called a 
COMMON block or program section (PSECT). VAX BASIC program mod- 
ules can access the values stored in the COMMON block by specifying a 
COMMON block with the same name. 


Format 
{ aaah } [ ( com-name ) ] {[data-type ] com-item},... 
num-unsubs-var 
num-array-name { [ int-const1 TO J int-const2,... ) 
str-unsubs-var = int-const 
eebeaes str-array-name { [ int-const1 TO | int-const2,... ) [ = int-const ] 

record-var 
FILL / { int-const ) ][ = int-const ] 
FILL% / ( int-const ) ] 
FILL$ [ ( int-const ) ][ = int-const ] 

Syntax Rules 


1. A COMMON block can have the same name as a program variable. 


2. A COMMON block and a map in the same program module cannot 
have the same name. 


3. All COMMON elements must be separated with commas. 


4. Com-name is optional. If you specify a com-name, it must be in paren- 
theses. If you do not specify a com-name, the default is “6BLANK”. 


5. Com-name can be from 1 through 31 characters. The first character 
of the name must be an alphabetic character (A through Z). The 
remaining characters, if present, can be any combination of letters, 
digits (0 through 9), dollar signs ($), periods (.), or underscores (—). 
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Data-type can be any VAX BASIC data type keyword or a data type 
defined in the RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2 in this manual. 


When you specify a data type, all following com-items, including FILL 
items, are of that data type until you specify a new data type. 


If you do not specify any data type, com-items take the current default 
data type and size. 


Com-item declares the name and format of the data to be stored. 


Num-unsubs-var and num-array-name specify a numeric variable or 
a numeric array. 


Record-var specifies a record instance. 


Str-unsubs-var and str-array-name specify a fixed-length string 
variable or array. You can specify the number of bytes to be 
reserved for the variable with the =int-const clause. The default 
string length is 16. 


When you specify either a numeric or a string array, VAX BASIC 
allows you to declare both lower and upper bounds. The upper 
bound is required; the lower bound is optional. 


— Int-const1 specifies the lower bounds of the array. 


— Int-const2 specifies the upper bounds of the array and, when 
accompanied by int-const1, must be preceded by the keyword 
TO. 


— Int-const1 must be less than or equal to int-const2. 


— If you do not specify int-const1, VAX BASIC uses zero as the 
default lower bound. 


— Int-const1 and int-const2 can be either negative or positive 
values. 


The FILL, FILL%, and FILL$ keywords allow you to reserve parts 
of the record buffer within or between data elements and to 
define the format of the storage. Int-const specifies the number 
of FILL items to be reserved. The =int-const clause allows you to 
specify the number of bytes to be reserved for string FILL items. 
Table 4—2 describes FILL item format and storage allocation. 


NOTE 


In the applicable formats of FILL, (int-const) represents a 
repeat count, not an array subscript. FILL (n) represents 
n elements, not n+ 1. 
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Table 4-2: FILL Item Formats and Storage Allocations 


FILL Format 
FILL 


FILL(int-const) 


FILL% 


FILL%(int-const) 


FILL$ 


FILL$(int-const) 
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Allocates storage for one element of 
the default data type unless preceded 
by a data-type; the number of bytes 
allocated depends on the default or 
the specified data type. 


Allocates storage for the number of 
floating-point elements specified by 
int-const unless preceded by a data 
type; the number of bytes allocated 
for each element depends on the 
default floating-point data size or the 
specified data type. 


Allocates storage for one integer ele- 
ment; the number of bytes allocated 
depends on the default integer size. 


Allocates storage for the number of 
integer elements specified by int- 
const; the number of bytes allocated 
for each element depends on the 
default integer size. 


Allocates 16 bytes of storage for a 
string element. The dollar sign can 
be omitted if the FILL keyword is 
preceded by the STRING data type. 


Allocates 16 bytes of storage for the 
number of string elements specified 
by int-const. The dollar sign can 
be omitted if the FILL keyword is 
preceded by the STRING data type. 


Remarks 


FILL Format 


FILL$=int-const 


COMMON 


Table 4-2 (Cont.): FILL Item Formats and Storage Allocations 


Storage Allocation 


Allocates the number of bytes of 


storage specified by int-const for a 
string element. The dollar sign can 
be omitted if the FILL keyword is 
preceded by the STRING data type. 


FILL$(int-const1)=int-const2 Allocates the number of bytes of 


storage specified by int-const2 for the 
number of string elements specified 
by int-const1. The dollar sign can 
be omitted if the FILL keyword is 
preceded by the STRING data type. 


Variables in a common are not initialized by VAX BASIC. 


A COMMON area and a MAP area with the same name, in different 
program modules, specify the same storage area. 


VAX BASIC does not execute COMMON statements. The COMMON 
statement allocates and defines the data storage area at compilation 
time. 


When you link your program, the size of the COMMON area is 

the size of the largest COMMON area with that name. VAX BASIC 
concatenates COMMON statements with the same com-name within a 
single program module into a single PSECT. The total space allocated 
is the sum of the space allocated in the concatenated COMMON 
statements. 


If you specify the same com-name in several program modules, the 
size of the PSECT will be determined by the program module that has 
the greatest amount of space allocated in the concatenated COMMON 
statements. 


The COMMON statement must lexically precede any reference to 
variables declared in it. 


A COMMON area can be accessed by more than one program module, 
as long as you define the com-name in each module that references the 
COMMON area, 
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7. Variable names in a COMMON statement in one program module 
need not match those in another program module. 


8. Variables and arrays declared in a COMMON statement cannot be de- 
clared elsewhere in the program by any other declarative statements. 


9. The data type specified for com-items or the default data type and size 
determines the amount of storage reserved in a COMMON block: 


BYTE integers reserve 1 byte. 

WORD integers reserve 2 bytes. 

LONG integers reserve 4 bytes. 

SINGLE floating-point numbers reserve 4 bytes. 

DOUBLE floating-point numbers reserve 8 bytes. 

GFLOAT floating-point numbers reserve 8 bytes. 

HFLOAT floating-point numbers reserve 16 bytes. 
DECIMAL(d,s) packed decimal numbers reserve (d+1)/2 bytes. 


STRING reserves 16 bytes (the default) or the number of bytes 
you specify with =int-const. 


10. For multi-dimensional arrays, values are assigned in row-column 
order. 


COMMON (sales_rec) DECIMAL net_sales (1965 TO 1975) 


STRING row = 2, 
report_name = 24 

DOUBLE FILL, 

LONG part_bins 


& & & & 
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COMP% 


The COMP% function compares two numeric strings and returns a -1, 0, 
or 1, depending on the results of the comparison. 


Format 


int-var = COMP% (str-exp1, str-exp2) 


Syntax Rules 


Str-exp1 and str-exp2 are numeric strings. They must have one of the 
following formats: 


Remarks 


Se, Ae 


An optional minus sign (-), ASCII digits, and an optional decimal 
point (.) 

An optional minus sign, ASCII digits, an optional decimal point, the 
letter E, an optional minus sign, and a 2-digit exponent 


If str-exp1 is greater than str-exp2, COMP% returns a 1. 
If the string expressions are equal, COMP% returns a 0. 
If.str-exp1 is less than str-exp2, COMP% returns a -1. 


The value returned by the COMP% function is an integer of the 
default size. 
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DECLARE STRING num_string, old_num_string, & 
INTEGER result 

num_string = "-24.5" 

old_num_string = "33" 

result = COMP%(num_string, old_num_string) 

PRINT "The value is ";result 


Output 


The value is -1 
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CONTINUE 


The CONTINUE statement causes VAX BASIC to clear an error condition 
and resume execution at the statement following the statement that caused 
the error or at the specified target. 


Format 


CONTINUE / target ] 
Syntax Rules 


If you specify a target, it must be a label or line number that appears either 
inside the associated protected region, inside a WHEN block protected 
region that surrounds the current protected region, or in an unprotected 
region of code. 


Remarks 


1. CONTINUE with no target causes VAX BASIC to transfer control to 
the statement immediately following the statement that caused the 
error. The next remark is an exception to this rule. 


2. If an error occurs on a FOR, NEXT, WHILE, UNTIL, SELECT or 
CASE statement, control is transferred to the statement immediately 
following the corresponding NEXT or END SELECT statement. For 
example: 
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10 WHEN ERROR IN 


A=10 
B=1 
20 FOR I=A TO B STEP 2 
30 GET #1 
40 C=1 
NEXT I 
50 C=0 
USE 
CONTINUE 
END WHEN 


If an error occurs on line 20, the CONTINUE statement transfers 
control to line 50. If an error occurs on line 30, program control 


resumes at line 40. 


3. The CONTINUE statement must be lexically inside of a handler. 
If you specify a CONTINUE statement within a detached handler, you 


cannot specify a target. 


WHEN ERROR USE err_handler 


END WHEN 


HANDLER err_handler 
SELECT ERR 
CASE = 50 
PRINT "Insufficient data" 
CONTINUE 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END HANDLER 
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The COS function returns the cosine of an angle in radians or degrees. 


Format 


real-var = COS (real-exp) 
Syntax Rules 
None. 
Remarks 


1. The returned value is between -1 and 1. This value is expressed in 
either radians or degrees depending on which angle clause you choose 
with the OPTION statement. 


2. VAX BASIC expects the argument of the COS function to be a real 
expression. When the argument is a real expression, VAX BASIC 
returns a value of the same floating-point size. When the argument is 
not a real expression, VAX BASIC converts the argument to the default 
floating-point size and returns a value of the default floating-point 
size. 


DECLARE SINGLE cos_value 
cos_value = 26 
PRINT COS (cos_value) 


Output 
646919 
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The CTRLC function enables CTRL/C trapping. When CTRL/C trap- 
ping is enabled, a CTRL/C typed at the terminal causes control to be 
transferred to the error handler currently in effect. 


Format 


int-var = CTRLC 
Syntax Rules 
None. 
Remarks 


1. When VAX BASIC encounters a CTRL/C, control passes to the error 
handler currently in effect. If there is no error handler in a program, 
the program aborts. 


2. Ina series of linked subprograms, setting CTRL/C for one subprogram 
enables CTRL/C trapping for all subprograms. 


3. When you trap a CTRL/C with an error handler, your program may 
be in an inconsistent state; therefore, you should handle the CTRL/C 
error and exit the program as quickly as possible. 


4. CTRL/C trapping is asynchronous; that is, VAX BASIC suspends 
execution and signals “Programmable “C trap” (ERR=28) as soon as 
it detects a CTRL/C. Consequently, a statement can be interrupted 
while it is executing. A statement so interrupted may be only partially 
executed and variables may be left in an undefined state. 


5. VAX BASIC can trap more than one CTRL/C error in a program as 
long as the error does not occur while the error handler is executing. 
If a second CTRL/C is detected while the error handler is processing 
the first CTRL/C, the program aborts. 


6. The CTRLC function always returns a value of zero. 
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7. The function RCTRLC disables CRTL/C trapping. See the description 
of the RCTRLC function for further details. 
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Example 


WHEN ERROR USE repair_work 
Y% = CTRLC 


END WHEN 
HANDLER repair_work 
IF (ERR=28) THEN PRINT "Interrupted by CTRLC!" 


END HANDLER 
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CVTSS 


The CVT$$ function is a synonym for the EDIT$ function. See the EDIT$ 
function for more information. 


NOTE 


DIGITAL recommends that you use the EDIT$ function rather 
than the CVT$$ function for new program development. 


Format 


str-var = CVTS$$ (str-exp, int-exp) 
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CVTxx 


The CVT$% function maps the first two characters of a string into a 
16-bit integer. The CVT%$ function translates a 16-bit integer into a 2- 
character string. The CVT$F function maps a 4- or 8-character string into 
a floating-point variable. The CVTF$ function translates a floating-point 
number into a 4- or 8-byte character string. The number of characters 
translated depends on whether the floating-point variable is single- or 
double-precision. 


NOTE 


CVT functions are supported only for compatibility with 
BASIC-PLUS. DIGITAL recommends that you use VAX BASIC’s 
dynamic mapping feature or multiple MAP statements for new 
program development. 


Format 
int-var = CVT$% (str-var) 
real-var = CVT$F (str-var) 
str-var = CVT%$ (int-var) 
str-var = CVTF$ (real-var) 


Syntax Rules 


CVT functions reverse the order of the bytes when moving them to or 
from a string. Therefore, you can mix MAP and MOVE statements, but 
you cannot use FIELD and CVT functions on a file if you also plan to use 
MAP or MOVE statements. 
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Remarks 


CVT$% 


If the CVT$% str-var has fewer than two characters, VAX BASIC 
pads the string with nulls. 

If the default data type is LONG, only two bytes of data are 
extracted from str-var; the high-order byte is sign-extended into a 
longword. 


The value returned by the CVT$% function is an integer of the 
default size. 


CVT%$ 


Only two bytes of data are inserted into str-var. 


If you specify a floating-point variable for int-var, VAX BASIC 
truncates it to an integer of the default size. If the default size is 
BYTE and the value of int-var exceeds 127, VAX BASIC signals an 
error. 


CVT$F 


CVT$F maps 4 characters when the program is compiled with 
/SINGLE and eight characters when the program is compiled with 
/DOUBLE. 


If str-var has fewer than four or eight characters, VAX BASIC pads 
the string with nulls. 


The real-var returned by the CVT$F function is the default 
floating-point size. If the default size is GFLOAT or HFLOAT, 
VAX BASIC signals the error “Floating CVT illegal for GFLOAT or 
HFLOAT”. 


CVTF$ 


The CVTF$ function maps single-precision numbers to a 4- 
character string and double-precision numbers to an 8-character 
string. 

VAX BASIC expects the argument of the CVTF$ function to be 

a real expression. When the argument is a real expression, VAX 
BASIC returns a value of the same floating-point size. When 
the argument is not a real expression, VAX BASIC converts the 
argument to the default floating-point size and returns a value of 
the default floating-point size. If the default floating-point size is 
GFLOAT or HFLOAT, VAX BASIC signals the error “Floating CVT 
illegal for GFLOAT or HFLOAT”. 
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CVTxx 


Examples 


Example 1 


DECLARE STRING test_string, another_string 
DECLARE LONG first_number, next_number 
test_string = "AT" 

PRINT CVT$%(test_string) 
another_string = "at" 

PRINT CVT$%(another_string) 
first_number = 16724 

PRINT CVT%$(first_number) 

next_number = 24948 

PRINT CVT%$(next_number) 

END 


Output 1 


16724 
24948 
AT 
at 


Example 2 


DECLARE STRING test_string, another_string 
DECLARE SINGLE first_num, second_num 
test_string = "DESK" 

first_num = CVT$F(test_string) 

PRINT first_num 

another_string = "desk" 

second_num = CVT$F(another_string) 
PRINT second_num 

PRINT CVTF$(first_num) 

PRINT CVTF$(second_num) 

END 


Output 2 


.218256E+12 
.466242E+31 
DESK 
desk 
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DATA 


The DATA statement creates a data block for the READ statement. 


Format 
num-lit 
DATA Str-lit |. 
ung-str 


Syntax Rules 


1. Num-lit specifies a numeric literal. 


2. Str-lit is a character string that starts and ends with double or single 
quotation marks. The quotation marks must match. 


3. Ung-str is a character sequence that does not start or end with double 
quotation marks and does not contain a comma. 


4. Commas separate data elements. If a comma is part of a data item, 
the entire item must be enclosed in quotation marks. 


Remarks 


1. Because VAX BASIC treats comment fields in DATA statements as part 
of the DATA sequence, you should not include comments. 


2. A DATA statement must be the last or the only statement on a 
physical line. 

3. DATA statements must end with a line terminator. 

4. When a DATA statement is continued with an ampersand (&), VAX 
BASIC interprets all characters between the keyword DATA and 


the ampersand as part of the data. Any code that appears on a 
noncontinued line is considered a new statement. 
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Example 


10. 


11. 


12. 


10 


DATA 


You cannot use the percent sign suffix for integer constants that appear 
in DATA statements. An attempt to do so causes VAX BASIC to signal 
the error, “Data format error” (ERR=50). 


DATA statements are local to a program module. 


VAX BASIC does not execute DATA statements. Instead, control is 
passed to the next executable statement. 


A program can have more than one DATA statement. VAX BASIC 
assembles data from all DATA statements in a single program unit 
into a lexically ordered single data block. 


VAX BASIC ignores leading and trailing blanks and tabs unless they 
are in a string literal. 


Commas are the only valid data delimiters. You must use a quoted 
string literal if a comma is to be part of a string. 


VAX BASIC ignores DATA statements without an accompanying 
READ statement. 


VAX BASIC signals the error “Data format error” if the DATA item 
does not match the data type of the variable specified in the READ 
statement or if a data element that is to be read into an integer variable 
ends with a percent sign (%). If a string data element ends with a 
dollar sign ($), VAX BASIC treats the dollar sign as part of the string. 


DECLARE INTEGER A,B,C 
READ A,B,C 

DATA 1,2,3 

PRINT A+B+C 


Output 


6 
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DATES 


The DATE$ function returns a string containing a day, month, and year in 
the form dd-Mmm-yy. 


Format 


str-var = DATES (int-exp) 
Syntax Rules 


1. Int-exp can have up to six digits in the form yyyddd, where the charac- 
ters yyy specify the number of years since 1970 and the characters ddd 
specify the day of that year. 


2. You must fill all three of the d positions with digits or zeros before 
you can fill the y positions. For example: 


e DATE$(121) returns the date 01-May-70, day 121 of the year 
1970. 


e DATE$(1201) returns the date 20-Jul-71, day 201 of the year 
1971. 


¢ DATE$(12001) returns the date 01-Jan-82, day one of the year 
1982. 


¢ DATE$(10202) returns the date 21-Jul-80, day 202 of the year 
1980. 
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Remarks 


DATES 


1. If int-exp equals zero, DATE$ returns the current date. 


2. The str-var returned by the DATE$ function consists of nine characters 
and expresses the day, month, and year in the form dd-Mmm-yy. 


3. If you specify an invalid date, such as day 385, results are unpre- 
dictable. 


4. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


DECLARE STRING todays_date 
todays_date = DATE$(0) 
PRINT todays_date 


Output 
26-Aug-86 
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DECIMAL 


The DECIMAL function converts a numeric expression or numeric string 
to the DECIMAL data type. 


Format 


decimal-var = DECIMAL (exp [, int-const1, int-const2 ] ) 
Syntax Rules 


1. Int-const1 specifies the total number of digits (the precision) and int- 
const2 specifies the number of digits to the right of the decimal point 
(the scale). If you do not specify these values, VAX BASIC uses the d 
(digits) and s (scale) defaults for the DECIMAL data type. 


2. Int-const1 and int-const2 must be positive integers from 1 through 31. 
Int-const2 cannot exceed the value of int-const1. 


3. Exp can be either numeric or numeric string. If a numeric string, it can 
contain the ASCII digits 0 through 9, uppercase E, a plus sign (+), a 
minus sign (—), and a period (.). 


Remarks 


1. If exp is a string, VAX BASIC ignores leading and trailing spaces and 
tabs. 


2. The DECIMAL function returns a zero when a string argument 
contains only spaces and tabs, or when it is null. 
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DECLARE STRING CONSTANT format_string = "##.###" 
DECLARE STRING num_value, DECIMAL(5,3) B 

INPUT "Enter a numeric value";num_value 

B = DECIMAL(num_value,5,3) 

PRINT USING format_string, B 


Output 


Enter a numeric value? 6 
6.000 


DECIMAL 
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DECLARE 


The DECLARE statement explicitly assigns a name and a data type to a 
variable, an entire array, a function, or a constant. 


Format 


Variables 
DECLARE  data-type { decl-item [,[ data-type ] decl-item ]},... 


DEF Functions 


DECLARE data-type FUNCTION { def-name [ ( [ def-param ],... ) ] },... 


Named Constants 


DECLARE data-type CONSTANT ( const-name = const-exp },... 


array-name ( [ int-const? TO | int-const2,...) 
decl-item: record-var 
unsubs-var 


def-param: _ data-type 


Syntax Rules 


1. Data-type can be any VAX BASIC data type keyword or a data type 
defined by a RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2 in this manual. 


2. Variables 
e Decl-item names an array, a record, or a variable. 


e A decl-item named in a DECLARE statement cannot be named 
in another DECLARE statement, or in a DEF, EXTERNAL, 
FUNCTION, SUB, COMMON, MAP, DIM, HANDLER, or 
PICTURE statement. 
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DECLARE 


Each decl-item is associated with the preceding data type. A data 
type is required for the first decl-item. 


Decl-items of data type STRING are dynamic strings. 


When you declare an array, VAX BASIC allows you to specify 
both lower and upper bounds for each dimension of the array. 
The upper bound is required; the lower bound is optional. 


— Int-const1 specifies the lower bounds of the array. 


— Int-const2 specifies the upper bounds of the array and, when 
accompanied by int-const1, must be preceded by the keyword 
TO. 


— Int-const1 must be less than or equal to int-const2. 


— If you do not specify int-const1, VAX BASIC uses zero as the 
default lower bound. 


— Int-const1 and int-const2 can be any combination of negative 
or positive values or zero. 


3. DEF Functions 


Def-name names the DEF function. 
Data-type specifies the data type of the value the function returns. 


Def-params specify the number and, optionally, the data type of 
the DEF parameters. Parameters define the arguments the DEF 
expects to receive when invoked. 


— When you specify a data type, all following parameters are of 
that data type until you specify a new data type. 


— If you do not specify any data type, parameters take the 
current default data type and size. 


— The number of parameters equals the number of commas plus 
1. For example, empty parentheses specify one parameter of 
the default type and size; one comma inside the parentheses 
specifies two parameters of the default type and size; and 
so on. One data type inside the parentheses specifies one 
parameter of the specified data type; two data types separated 
by one comma specifies two parameters of the specified type, 
and so on. 
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Remarks 


Named Constants 

e Const-name is the name you assign to the constant. 

e Data-type specifies the data type of the constant. The value of the 
const must be numeric if the data type is numeric and string if the 


data type is STRING. If the data type is STRING, const must be a 
quoted string or another string constant. 


¢ Const-exp cannot be of the RFA data type. 
e String constants cannot exceed 498 characters. 


e VAX BASIC allows const-exp to be an expression for all data types 
except DECIMAL. Expressions are not allowed as values when 
you name DECIMAL constants. 


e Allowable operators in DECLARE CONSTANT expressions in- 
clude all valid arithmetic, relational, and logical operators except 
exponentiation. Built-in functions cannot be used in DECLARE 
CONSTANT expressions. The following examples use valid 
expressions as values: 


DECLARE DOUBLE CONSTANT max_value = (PI/2) 
DECLARE STRING CONSTANT left_arrow = "<----- "+ LF + CR 


The DECLARE statement is not executable. 


The DECLARE statement must lexically precede any reference to the 
variables, functions, or constants named in it. 


To declare a virtual or run-time array, use the DIMENSION statement. 
Variables 


e Subsequent decl-items are associated with the specified data type 
until you specify another data type. 


e All variables named in a DECLARE statement are initialized to 
zero if numeric or to the null string if string. 
DEF Functions 


e The DECLARE FUNCTION statement allows you to name a 
function defined in a DEF or DEF* statement, specify the data type 
of the value the function returns, and declare the number and data 
type of the DEF parameters. 


e Data type keywords must be separated by commas. 
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DECLARE 


The first specification of a data type for a def-param is the default 
for subsequent arguments until you specify another def-param. For 
example: 


DECLARE DOUBLE FUNCTION interest (DOUBLE, SINGLE, ,) 


This example declares two parameters of the default type and size, 
one DOUBLE parameter, and three SINGLE parameters for the 
function named interest. 


6. Named Constants 


The DECLARE CONSTANT statement allows you to name a 
constant value and assign a data type to that value. Note that 
you can specify only one data type in a DECLARE CONSTANT 
statement. To declare a constant of another data type, you must 
use a second DECLARE CONSTANT statement. 


During program execution, you cannot change the value assigned 
to the constant. 


The specified data-type determines the data type of the constant. 
For example: 

DECLARE LONG CONSTANT True = -1, False = 0 

DECLARE REAL CONSTANT 22Z = 123.0 

DECLARE BYTE CONSTANT YYY = '123'L 

PRINT True, False, ZZZ, YYY 


Output 


=a 0 123 123 


In this example, VAX BASIC truncates the LONG value assigned 
to YYY to a BYTE variable. 


NOTE 


Data types specified in a DECLARE statement override any 
defaults specified in COMPILE command qualifiers or OPTION 
statements. 
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Example 1 


!DEF Functions 
DECLARE INTEGER FUNCTION amount(, ,DOUBLE,BYTE, ,) 


Example 2 


!Named Constants 
DECLARE DOUBLE CONSTANT interest_rate = 15.22 


4-52 Statements and Functions 


DEF 


DEF 


The DEF statement lets you define a single- or multi-line function. 


Format 
Single-line DEF 

DEF / data-type ] def-name [ ( [ data-type ] var ,...) ] = exp 
Multi-Line DEF 

DEF / data-type ] def-name [ ( [ data-type var ],...) ] [ statement J... 


[ statement ]... 
END DEF 

FNEND [exp J 
Syntax Rules 


1. Data-type can be any VAX BASIC data type keyword or a data type 
defined in the RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2 in this manual. 

2. The data type that precedes the def-name specifies the data type of the 
value returned by the DEF function. 

3. Def-name is the name of the DEF function. The def-name can contain 
from 1 to 31 characters. 

4. If the def-name also appears in a DECLARE FUNCTION statement, 
the following rules apply: 


¢ A function data type is required. 


e The first character of the def-name must be an alphabetic character 
(A through Z). The remaining characters can be any combination 
of letters, digits (0 through 9), dollar signs ($), underscores (_), 
or periods (.). 
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10. 


11. 


If the def-name does not appear in a DECLARE FUNCTION statement, 
but the DEF statement appears before the first reference to the def- 
name, the following rules apply: 


e The function data type is optional. 


e The first character of the def-name must be an alphabetic letter (A 
through Z). The remaining characters can be any combination of 
letters, digits, dollar signs, underscores, or periods. 


e If a function data type is not specified, the last character in the 
def-name must be a percent sign for an INTEGER function, or a 
dollar sign for a STRING function. 


If the def-name does not appear in a DECLARE FUNCTION statement, 
and the DEF statement appears after the first reference to the def-name, 
the following rules apply: 


e The function data type cannot be present. 


e The first two characters of the def-name must be FN. The remain- 
ing characters can be any combination of letters, digits, dollar 
signs, underscores, or periods, with one restriction: the last char- 
acter must be a percent sign for an INTEGER function, or a dollar 
sign for a STRING function. 


e There must be at least one character between the FN characters 
and the ending dollar sign or percent character. FN$ and FN% are 
not valid function names. 


Var specifies optional formal DEF parameters. Because the parameters 
are local to the DEF function, any reference to these variables outside 
the DEF body creates a different variable. 


You can specify the data type of DEF parameters with a data type 
keyword or with a data type defined in a RECORD statement. If you 
do not include a data type, the parameters are of the default type and 
size. Parameters that follow a data type keyword are of the specified 
type and size until you specify another data type. 

You can specify up to 255 parameters in a DEF statement. 
Single-Line DEF 

Exp specifies the operations the function performs. 

Multi-Line DEF 

e Statements specifies the operations the function performs. 


¢ The END DEF or FNEND statement is required to end a multi-line 
DEF. 
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Remarks 


DEF 


e VAX BASIC does not allow you to specify any statements that 


indicate the beginning or end of any SUB, FUNCTION, PICTURE, 
HANDLER (attached handlers are legal), PROGRAM or DEF in a 
function definition. 


e Exp specifies the function result. Exp must be compatible with the 


DEF data type. 


When VAX BASIC encounters a DEF statement, control of the program 
passes to the next executable statement after the DEF. 


The function is invoked when you use the function name in an 
expression. 


You cannot specify how parameters are passed. When you invoke 

a function, VAX BASIC evaluates parameters from left to right and 
passes parameters to the function so that they cannot be modified. 
Numeric parameters are passed by value and string parameters are 
passed by descriptor, where the descriptor points to a local copy. 
DEF functions can reference variables in the main program, but they 
cannot reference variables in other DEF or DEF* functions. A DEF 
function can, therefore, modify other variables in the program, but not 
variables within another DEF function. 


A DEF function is local to the program, subprogram, function, or 
picture that defines it. 

You can declare a DEF either by defining it, by using the DECLARE 
FUNCTION statement, or by implicitly declaring it with a reference to 
the function in an expression. 

If your program invokes a function with a name that does not start 
with FN before the DEF statement defines the function, VAX BASIC 
signals an error. 

If the number of parameters, types of parameters, or type of result 
declared in the invocation disagree with the number or types of 
parameters defined in the DEF statement, VAX BASIC signals an error. 
DATA statements in a multi-line DEF are not local to the func- 

tion; they are local to the program module containing the function 
definition. 

The function value is initialized to zero or the null string each time 
you invoke the function. 
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10. 


11. 


12. 


13); 


14. 


15. 


16. 


17, 


Examples 


You can invoke a DEF function within an attached or detached 
handler. 


DEF definitions cannot appear inside a protected region. However, a 
DEF can contain one or more protected regions. 
In DEF definitions that contain handlers, the following rules apply: 


e If the function was invoked from a protected region, the EXIT 
HANDLER statement transfers control to the handler specified for 
that protected region. 


e If the function was not invoked from a protected region, the 
EXIT HANDLER statement transfers control to the default error 
handler. 


If an exception is not handled within a DEF function, control is 
transferred to the module that invoked the DEF function. 


ON ERROR statements within a DEF function are local to the function. 


A CONTINUE, GOTO, GOSUB, ON ERROR GOTO, or RESUME 
statement in a multi-line function definition must refer to a line 
number or label in the same function definition. 


You cannot transfer control into a multi-line DEF except by invoking 
the function. 


DEF functions can be recursive. 


Example 1 


{Single-Line DEF 

DEF DOUBLE add (DOUBLE A, B, SINGLE C, D, EF) =A+B+C+Dt+E 
INPUT 'Enter five numbers to be added';V,W,X,Y,Z 

PRINT 'The sum is';ADD(V,W,X,Y,Z) 


Output 1 


Enter five numbers to be added? 1,2,3,4,5 
The sum is 15 
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Example 2 
PROGRAM I_want_a_raise 
OPTION TYPE = EXPLICIT, & 
CONSTANT TYPE = DECIMAL, & 


SIZE = DECIMAL (6,2) 


DECLARE DECIMAL CONSTANT Overtime_factor = 0.50 
DECLARE DECIMAL My_hours, My_rate, Overtime 
DECLARE DECIMAL FUNCTION Calculate_pay (DECIMAL, DECIMAL) 


INPUT “Your hours this week" ;My_hours 
INPUT "Your hourly rate";My_rate 


PRINT "My pay this week is"; Calculate_pay ( My_hours, My_rate ) 
DEF DECIMAL Calculate_pay (DECIMAL Hours, Rate) 


IF Hours = 0.0 
THEN 

EXIT DEF 0.0 
END IF 


Overtime = Hours - 40.0 


IF Overtime < 0.0 
THEN 

Overtime = 0.0 
END IF 


END DEF (Hours * Rate) + (Overtime * (Overtime_factor * Rate) ) 
END PROGRAM 


Output 2 


Your hours this week? 45.7 
Your pay rate? 20.35 
Your pay for the week is 987.95 
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DEF* 


The DEF* statement lets you define a single- or multi-line function. 


NOTE 


The DEF* statement is not recommended for new program 
development. DIGITAL recommends that you use the DEF 
statement for defining single- and multi-line functions. 


Format 


Single-line DEF« 


DEF* / data-type ] def-name [ ( [ data-type ] var ,...) ] = exp 


Multi-Line DEF« 


DEF* | data-type ] def-name [ ( [ data-type ] var ,...) ] [ statement J... 


[ statement ]... 
END DEF 
FNEND Lees 
Syntax Rules 


1. Data-type can be any VAX BASIC data type keyword or a data type 
defined in the RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2 in this manual. 


2. The data type that precedes the def-name specifies the data type of the 
value returned by the DEF* function. 


3. Def-name is the name of the DEF* function. The def-name can contain 


from 1 to 31 characters. 


4. If the def-name also appears in a DECLARE FUNCTION statement, 


the following rules apply: 
e A function data type is required. 
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DEF* 


e The first character of the def-name must be an alphabetic character 
(A through Z). The remaining characters can be any combination 
of letters, digits (0 through 9), dollar signs ($), underscores (_), 
or periods (.). 

If the def-name does not appear in a DECLARE FUNCTION statement, 

but the DEF* statement appears before the first reference to the 

def-name, the following rules apply: 


e The function data type is optional. 


e The first character of the def-name must be an alphabetic character 
(A through Z). The remaining characters can be any combination 
of letters, digits, dollar signs, underscores, or periods. 


e Ifa function data type is not specified, the last character in the 
def-name must be a percent sign for an INTEGER function, or a 
dollar sign for a STRING function. 


If the def-name does not appear in a DECLARE FUNCTION statement, 
and the DEF* statement appears after the first reference to the def- 
name, the following rules apply: 


e The function data type cannot be present. 


e The first two characters of the def-name must be FN. The remain- 
ing characters can be any combination of letters, digits, dollar 
signs, underscores, or periods, with one restriction: the last char- 
acter must be a percent sign for an INTEGER function, or a dollar 
sign for a STRING function. 


e There must be at least one character between the FN characters 
and the ending dollar sign or percent character. FN$ and FN% are 
not valid function names. 


Var specifies optional formal function parameters. 


You can specify the data type of function parameters with a data type 
keyword. If you do not specify a data type, parameters are of the 
default type and size. Parameters that follow a data type are of the 
specified type and size until you specify another data type. 


You can specify up to 8 parameters in a DEF* statement. 
Single-Line DEF* 

Exp specifies the operations the function performs. 
Multi-Line DEF* 

e Statements specifies the operations the function performs. 


e The END DEF or FNEND statement is required to end a multi-line 
DEF*. 
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e VAX BASIC does not allow you to specify any statements that 
indicate the beginning or end of any SUB, FUNCTION, PICTURE, 
HANDLER, PROGRAM or DEF in a function definition. 


e Exp specifies the function result. Exp must be compatible with the 
DEF data type. 


Remarks 


1. When VAX BASIC encounters a DEF* statement, control of the 
program passes to the next executable statement after the DEF*. 


2. A function defined by the DEF* statement is invoked when you use 
the function name in an expression. 


3. You cannot specify how parameters are passed. When you invoke a 
DEF* function, VAX BASIC evaluates parameters from left to right and 
passes parameters to the function so that they cannot be modified. 
Numeric parameters are passed by value, and string parameters are 
passed by descriptor, where the descriptor points to a local copy. 
DEF* functions can reference variables in the main program, but they 
cannot reference variables in other DEF or DEF* functions. A DEF* 
function can, therefore, modify variables in the program, but not 
variables within another DEF* function. 


4. The following differences exist between DEF* and DEF statements: 


e You can use the GOTO, ON GOTO, GOSUB, and ON GOSUB 
statements to a branch outside a multi-line DEF*, but they are not 
recommended. 


e Although other variables used within the body of a DEF* function 
are not local to the DEF* function, DEF* formal parameters are. 
However, if you change the value of formal parameters within a 
DEF* function and then transfer control out of the DEF* function 
without executing the END DEF or FNEND statement, variables 
outside the DEF* that have the same names as DEF* formal 
parameters are also changed. 


e You can pass up to 255 parameters to a DEF function. DEF* 
functions accept a maximum of 8 parameters. 


e A DEF* function value is not initialized when the DEF* function 
is invoked. Therefore, if a DEF* function is invoked, and no new 
function value is assigned, the DEF* function returns the value of 
its previous invocation. 
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DEF* 


e¢ The error handler of the program module that contains the DEF* 
is the default error handler for a DEF* function. Parameters return 
to their original values when control passes to the error handler. 


A DEF* is local to the program or subprogram that defines it. 


You can declare a DEF* either by defining it, by using the DECLARE 
FUNCTION statement, or by implicitly declaring it with a reference to 
the function in an expression. 


If the number of parameters, types of parameters, or type of result 
declared in the invocation disagree with the number or types of 
parameters defined in the DEF* statement, VAX BASIC signals an 
error. 


DEF* functions can be recursive. 


DATA statements in a multi-line DEF* are not local to the func- 
tion; they are local to the program module containing the function 
definition. 

You can invoke a DEF* function within an attached or detached 
handler. 


DEF* definitions cannot appear inside a protected region, but they can 
contain one or more protected regions. 


In DEF* functions that contain handlers, the following rules apply: 


e If the function was invoked from a protected region, the EXIT 
HANDLER statement transfers control to the handler specified for 
that protected region. 


e If the function was not invoked from a protected region, the 
EXIT HANDLER statement transfers control to the default error 
handler. 


Example 1 


'Single-Line DEF* 

DEF* STRING CONCAT(STRING A,B) = A+B 
DECLARE STRING word1,word2 

INPUT "Enter two words";word1,word2 
PRINT CONCAT (word1,word2) 
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Output 1 


Enter two words? TO 
? DAY 
TODAY 


Example 2 


!Multi-Line DEF* 

DEF* DOUBLE example(DOUBLE A, B, SINGLE C, D, E) 
EXIT DEF IF B = 0 
example = (A/B) + C - (D*E) 

END DEF 

INPUT "Enter 5 numbers";V,W,X,Y,Z 

PRINT example(V,W,X,Y,Z) 


Output 2 


Enter 5 numbers? 2,4,6,8,1 
-1.5 
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DELETE 


DELETE 


The DELETE statement removes a record from a relative or indexed file. 


Format 
DELETE #chnl-exp 


Syntax Rules 


Chnl-exp is a numeric expression that specifies a channel number asso- 
ciated with a file. It must be immediately preceded by a number sign 


(#). 
Remarks 


1. The DELETE statement removes the current record from a file. Once 
the record is removed, you cannot access it. 


2. The file specified by chnl-exp must have been opened with ACCESS 
MODIFY or WRITE. 


3. You can delete a record only if the last I/O statement executed on the 
specified channel was a successful GET or FIND operation. 


4. The DELETE statement leaves the current record pointer undefined 
and the next record pointer unchanged. 


5. VAX BASIC signals an error when the I/O channel is illegal or not 
open, when no current record exists, when access is illegal or illogical, 
or when the operation is illegal. 
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DELETE 


Example 
DECLARE STRING record_num 


OPEN "CUS.DAT" FOR INPUT AS #1, RELATIVE FIXED & 
ACCESS MODIFY, RECORDSIZE 40 


INPUT "WHICH RECORD WOULD YOU LIKE TO EXAMINE"; record_num 
GET #1, RECORD record_num 
DELETE #1 


Here, CUS.DAT is opened for input with ACCESS MODIFY. Once you en- 
ter the number of the record you want to retrieve and the GET statement 
executes successfully, the current record number is deleted. 
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DET 


DET 


The DET function returns the value of the determinant of the last matrix 
inverted with the MAT INV function. 


Format 


real-var = DET 
Syntax Rules 
None. 
Remarks 


1. When a matrix is inverted with the MAT INV statement, VAX BASIC 
calculates the determinant as a by-product of the inversion process. 
The DET function retrieves this value. 


2. If your program does not contain a MAT INV statement, the DET 
function returns a value of zero. 


3. The value returned by the DET function is a floating-point value of 
the default size. 
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DET 


Example 


MAT INPUT first_array(3,3) 

MAT PRINT first_array; 

PRINT 

MAT inv_array = INV (first_array) 
determinant = DET 

MAT PRINT inv_array; 

PRINT 

PRINT determinant 

PRINT 

MAT mult_larray = first_array * inv_array 
MAT PRINT mult_array; 


Output 
7 1,0,0,0,1,0,0,0,1 


oor fF OOF OOF 
oro 0OrFO0 
eK OOoO FOO 


oro 
or?) 
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DIFS 


The DIF$ function returns a numeric string whose value is the difference 
between two numeric strings. 


Format 


str-var = DIF$ (str-exp1, str-exp2) 
Syntax Rules 


Each str-exp can contain up to 54 ASCII digits, an optional decimal point, 
and an optional leading sign. 


Remarks 


1. VAX BASIC subtracts str-exp2 from str-exp1 and stores the result in 
str-var. 


2. The difference between two integers takes the precision of the larger 
integer. 


3. The difference between two decimal fractions takes the precision of 
the more precise fraction, unless trailing zeros generate that precision. 


4. The difference between two floating-point numbers takes precision as 
follows: 


e The difference of the integer parts takes the precision of the larger 
part. 


e The difference of the decimal fraction part takes the precision of 
the more precise part. 


5. VAX BASIC truncates leading and trailing zeros. 
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DIFS 


Example 


PRINT DIF$ ("689","-231") 


Output 
920 
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The DIMENSION statement creates and names a static, dynamic, or 
virtual array. The array subscripts determine the dimensions and the size 
of the array. You can specify the data type of the array and associate the 
array with an I/O channel. 


Format 


Nonvirtual, Nonexecutable 


DIM 
ta- ~ t- ti T 
{ DIMENSION \ {[ data-type ] array-name { [ int-const1 TO ] 
int-const2,... },...) 
Executable 
DIM : z 
{ DIMENSION {[ data-type ] array-name 
([ int-var1 TO ] int-var2,... ) },... 
Virtual 
{ DIM #chnl-exp, { [ data-type ] array-name 
DIMENSION 
( int-const,... ) [ = int-const ] },... 
Syntax Rules 


1. An array name in a DIM statement cannot also appear in a 
COMMON, MAP, or DECLARE statement. 


2. Data-type can be any VAX BASIC data type keyword or a data type 
defined in a RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2 in this manual. 
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If you do specify a data type and the array name ends in a percent 
sign (%) or dollar sign ($) suffix character, the variable must be a 
string or integer data type. 


If you do not specify a data type, the array name determines the type 
of data the array holds. If the array name ends in a percent sign, the 
array stores integer data of the default integer size. If the array name 
ends in a dollar sign, the array stores string data. Otherwise, the array 
stores data of the default type and size. 


An array can have up to 32 dimensions. Nonvirtual array sizes are 
limited by the virtual memory limits of your system. 


When you declare a nonvirtual array, VAX BASIC allows you to 


specify both lower and upper bounds. The upper bound is required; 
the lower bound is optional. 


e Int-const1 or int-var1 specifies the lower bounds of the array. 


e Int-const2 or int-var2 specifies the upper bounds of the array and, 
when accompanied by int-const1 or int-var1, must be preceded by 
the keyword TO. 


e  Int-const1 must be less than or equal to int-const2. Int-varl must 
be less than or equal to int-var2. 

e If you do not specify int-const1 or int-var1, VAX BASIC uses zero 
as the default lower bound. 

e Array dimensions can have either positive or negative values. 

Nonvirtual, Nonexecutable 

e When all the dimension specifications are integer constants, as 
in DIM A(15,10,20), the DIM statement is nonexecutable and the 
array size is static. A static array cannot appear in another DIM 


statement because VAX BASIC determines storage requirements at 
compilation time. 


e A nonexecutable DIM statement must lexically precede any 
reference to the array it dimensions. That is, you must dimension 
a static array before you can reference array elements. 

Virtual 


e The virtual array must be dimensioned and the file must be open 
before you can reference the array. 
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Remarks 


e When the data type is STRING, the =int-const clause specifies 
the length of each array element. The default string length is 16 
characters. Virtual string array lengths are rounded to the next 
higher power of 2. Therefore, specifying an element length of 12 
results in an actual length of 16. For example: 


DIM #1, STRING vir_array(100) = 12 
OPEN "STATS.BAS" FOR OUTPUT as #1, VIRTUAL 


Output 


“%BASIC-W-STRLENINC, virtual array string VIR_ARRAY length increased 
from 12 to 16 


Executable 


When any of the dimension specifications are integer variables as 

in DIM A(10%,20%,Y%), the DIM statement is executable and the 
array is dynamic. A dynamic array can be redimensioned with a DIM 
statement any number of times because VAX BASIC allocates storage 
at run time when each DIM statement is executed. 


You can create an array implicitly by referencing an array element 
without using a DIM statement. This causes VAX BASIC to create an 
array with dimensions of (10), (10,10), (10,10,10), and so on, depend- 
ing on the number of bounds specifications in the referenced array 
element. You cannot create virtual or executable arrays implicitly. 


VAX BASIC allocates storage for arrays by row, from right to left. 
Nonvirtual, Nonexecutable 


e¢ You can declare arrays with the COMMON, MAP, and DECLARE 
statements. Arrays so declared cannot be redimensioned with 
the DIM statement. Furthermore, string arrays declared with a 
COMMON or MAP statement are always fixed-length. 


e If you reference an array element declared in an array whose 
subscripts are smaller than the lower bound or larger than the 
upper bound specified in the DIM statement, VAX BASIC signals 
the error “Subscript out of range” (ERR=55). 
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4. Virtual 


For new development, DIGITAL does not recommend virtual 
arrays. 


When the rightmost subscript varies faster than the subscripts to 
the left, fewer disk accesses are necessary to access array elements 
in virtual arrays. 


Using the same DIM statement for multiple virtual arrays allocates 
all arrays in a single disk file. The arrays are stored in the order 
they were declared. 


Any program or subprogram can access a virtual array by declar- 
ing it in a virtual DIMENSION statement. For example: 


DIM #1, A(10) 
DIM #1, B(10) 


In this example, array B overlays array A. You must specify the 
same channel number, data types, and limits in the same order as 
they occur in the DIM statement that created the virtual array. 


VAX BASIC stores a string in a virtual array by padding it with 
trailing nulls to the length of the array element. It removes 
these nulls when it retrieves the string from the virtual array. 
Remember that string array element sizes are always rounded to 
the next power of 2. 


The OPEN statement for a virtual array must include the 
ORGANIZATION VIRTUAL clause for the channel specified 
in the DIMENSION statement. 


VAX BASIC does not initialize virtual arrays and treats them as 
statically allocated arrays. You cannot redimension virtual arrays. 


Refer to the VAX BASIC User Manual for more information on 
virtual arrays. 


5. Executable 


You create an executable, dynamic array by using integer variables 
for array bounds, as in DIM A(Y%,X%). This eliminates the need 
to dimension an array to its largest possible size. Array bounds 
in an executable DIM statement can be constants or variables, but 
not expressions. At least one bound must be a variable. 


You cannot reference an array named in an executable DIM 
statement until after the DIM statement executes. 
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Examples 


e You can redimension a dynamic array to make the bounds of 
each dimension larger or smaller, but you cannot change the 
number of dimensions. For example, you cannot redimension a 
four-dimensional array to be a five-dimensional array. 


e The executable DIM statement cannot be used to dimension virtual 
arrays, arrays received as formal parameters, or arrays declared in 
COMMON, MAP, or nonexecutable DIM statements. 


e An executable DIM statement always reinitializes the array to zero 
(for numeric arrays) or to the null string if string. 


e If you reference an array element declared in an executable DIM 
statement whose subscripts are not within the bounds specified 
in the last execution of the DIM, VAX BASIC signals the error 
“Subscript out of range” (ERR=55). 


Example 1 


!Nonvirtual, Nonexecutable 
DIM STRING name_list(20 TO 100), BYTE age(100) 


Example 2 


Virtual 
DIM #1%, STRING name_list(500), REAL amount(10,10) 


Example 3 


!Executable 
DIM DOUBLE inventory (base ,markup) 


DIM DOUBLE inventory (new_base,new_markup) 
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ECHO 


The ECHO function causes characters to be echoed at a terminal that is 
opened on a specified channel. 


Format 


int-var = ECHO (chni-exp) 
Syntax Rules 


Chnl-exp must specify a terminal. 


Remarks 
1. The ECHO function is the complement of the NOECHO function; 
each function disables the effect of the other. 
2. The ECHO function has no effect on an unopened channel. 
3. The ECHO function always returns a value of zero. 
Example 


DECLARE INTEGER Y, & 
STRING pass_word 

Y = NOECHO(0%) 

SET NO PROMPT 

INPUT "Enter your password: ";pass_word 

Y = ECHO(0%) 


IF pass_word = "Darlene" 
THEN 

PRINT CR+LF+"YOU ARE CORRECT !" 
END IF 
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ECHO 


Output 


Enter your password? 
YOU ARE CORRECT ! 
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EDITS 


The EDIT$ function performs one or more string editing functions, de- 
pending on the value of its integer argument. 


Format 


str-var = EDIT$ (str-exp, int-exp) 
Syntax Rules 
None. 
Remarks 


VAX BASIC edits str-exp to produce str-var. 


2. The editing that VAX BASIC performs depends on the value of int-exp. 
Table 4-3 describes EDIT$ values and functions. 


3. All values are additive; for example, you can perform the editing 
functions of values 8, 16, and 32 by specifying a value of 56. 


4. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


Table 4-3: EDITS Values 
Value Edit Performed 


1 Discards each character’s parity bit (bit 7) 

2 Discards all spaces and tabs 

4 Discards all carriage returns <CR> , line feeds <LF> , form feeds 
<FF> , deletes <DEL> , escapes <ESC> , and nulls <NUL> 

8 Discards leading spaces and tabs 
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EDITS 


Table 4—3 (Cont.): EDITS Values 


Value 


16 
32 
64 


128 
256 


Edit Performed 


Converts multiple spaces and tabs to a single space 


Converts lowercase letters to uppercase letters 


Converts left bracket ([) to left parenthesis [(] and right bracket (]) to 
right parenthesis [)] 


Discards trailing spaces and tabs (same as TRM$ function) 


Suppresses all editing for characters within quotation marks; if the 
string has only one quotation mark, VAX BASIC suppresses all editing 


for the characters following the quotation mark 


DECLARE STRING old_string, new_string 

old_string = "a value of 32 converts lowercase letters to uppercase" 
new_string = EDIT$(old_string,32) 

PRINT new_string 


Output 


A VALUE OF 32 CONVERTS LOWERCASE LETTERS TO UPPERCASE 
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The END statement marks the physical and logical end of a main program, 
a program module, or a block of statements. 


Format 
END [ block ] 


DEF/ exp | 
FUNCTION/ exp / 
GROUP 
RECORD 
VARIANT 
IF 

block: 1 HANDLER 
PICTURE 
PROGRAM, int-exp ] 
SELECT 
WHEN 
SUB 


Syntax Rules 


None. 
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Remarks 


The END statement with no block keyword marks the end of a main 
program. The END or END PROGRAM statement must be the last 
statement on the last lexical line of the main program. 


The END statement followed by a block keyword marks the end of a 
program, a VAX BASIC SUB, FUNCTION, or PICTURE subprogram, a 
DEF, an IF, a HANDLER, a PROGRAM, a SELECT statement block or 
a WHEN block. 


END RECORD, END GROUP, and END VARIANT mark the end 
of a RECORD statement, or a GROUP component or VARIANT 
component of a RECORD statement. 

END DEF and END FUNCTION 


e When VAX BASIC executes an END DEF or an END FUNCTION 
statement, it returns the function value to the statement that 
invoked the function and releases all storage associated with the 
DEF or FUNCTION. 


e If you specify an optional expression with the END DEF or END 
FUNCTION statement, the expression must be compatible with 
the DEF or FUNCTION data type. The expression is the function 
result unless an EXIT DEF or EXIT FUNCTION statement is 
executed. This expression supersedes all function assignments. 


e The END DEF statement restores the error handler in effect when 
the DEF was invoked (this is not true of the DEF* statement). 

e The END FUNCTION statement does not affect I/O operations or 
files. 


END HANDLER 


The END HANDLER statement causes VAX BASIC to transfer control 
to the statement following the WHEN block with the exception 
cleared. 


END PROGRAM 


e The END PROGRAM statement allows you to end a program 
module. 


e An optional integer expression specifies the exit status of the 
program that is reported to DCL. This status is overridden by a 
status expression in an EXIT PROGRAM statement. 


e You can specify an END PROGRAM statement without a match- 
ing PROGRAM statement. 
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10. 


11. 


10 


END WHEN 


e The END WHEN statement ends a WHEN block and transfers 
control to the statement following the WHEN block. 


e If the END WHEN statement ends an attached handler, control is 
transferred to the statement following the WHEN block with the 
exception cleared. 


END SUB 
e The END SUB statement does not affect I/O operations or files. 


e The END SUB statement releases the storage allocated to local 
variables and returns control to the calling program. 


e The END SUB statement cannot be executed in an error handler 
unless the END SUB is in a subprogram called by the error 
handler of another routine. 


When an END or END PROGRAM statement marking the end of a 
main program executes, VAX BASIC closes all files and releases all 
program storage. 


If you use ON ERROR error handling, you must clear any errors with 
the RESUME statement before executing an END PROGRAM, END 
SUB, END FUNCTION or END PICTURE statement. 


Except for the END PROGRAM statement, VAX BASIC signals an 
error when a program contains an END block statement with no 
corresponding and preceding block keyword. 


INPUT "Guess a number"; AY 
IF AY = 24 
THEN 
PRINT, "YOU GUESSED IT!" 
END IF 
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IF AX < 24 
THEN 
PRINT, “BIGGER IS BETTER!" 
GOTO 10 
END IF 


IF A% > 24 

THEN 
PRINT, "SMALLER IS BETTER!" 
GOTO 10 

END IF 


END PROGRAM 
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ERL 


ERL 


The ERL function returns the number of the BASIC line where the last 
error occurred. 


Format 


int-var = ERL 
Syntax Rules 
The value of int-var returned by the ERL function is a LONG integer. 
Remarks 


1. If the ERL function is used before an error occurs or after an error is 
handled, the results are undefined. 

2. The ERL function overrides the /NOLINE qualifier. If a program 
compiled with the /NOLINE qualifier in effect contains an ERL 
function, VAX BASIC signals the message “ERL overrides NOLINE”. 
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10 


20 
30 


DECLARE LONG int_exp 
WHEN ERROR USE error_routine 
INPUT "Enter an integer expression"; int_exp 
PRINT DATE$(int_exp) 
END WHEN 
HANDLER error_routine 
IF ERL = 20 
THEN 
PRINT "Invalid input...try again" 
RETRY 
ELSE 
PRINT "UNEXPECTED ERROR" 
EXIT HANDLER 
END IF 
END HANDLER 
END PROGRAM 


Output 


Enter an integer expression? ABCD 
Error occurred on line 20 
Enter an integer expression? 3211 


30- 


Jul-73 
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ERNS 


The ERN$ function returns the name of the main program, subprogram, 
or DEF function that was executing when the last error occurred. 


Format 


str-var = ERNS$ 


Syntax Rules 

None. 

Remarks 

1. If the ERN$ function executes before an error occurs or after an error 
is handled, ERN$§ returns a null string. 

2. If you call a subprogram or function compiled with /NOSETUP or 
containing an OPTION INACTIVE=SETUP statement, the ERN§$ 
function will not have a valid value if an exception occurs in the called 
procedure. 

Example 
10 DECLARE LONG int_exp 


{This module's name is DATE 
WHEN ERROR IN 
INPUT "Enter an number"; int_exp 
USE 
PRINT "Error in module ";ERN$ 
RETRY 
END WHEN 
PRINT Date$(int_exp) 
END 
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Output 


Enter a number? ABCD 
Error in module DATE 
Enter a number? 0 
21-May-86 


ERNS 
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The ERR function returns the error number of the current run-time error. 


Format 


int-var = ERR 
Syntax Rules 


The value of int-var returned by the ERR function is always a LONG 
integer. 


Remarks 


If the ERR function is used before an error occurs or after an error is 
handled, the results are undefined. 


Example 


10 DECLARE LONG int_exp 
WHEN ERROR USE error_routine 
20 INPUT "Enter an integer expression"; int_exp 
PRINT DATE$(int_exp) 
END WHEN 
HANDLER error_routine: 
PRINT "Error number"; ERR 
IF ERR = 50 THEN PRINT "DATA FORMAT ERROR" 
ELSE PRINT “UNEXPECTED ERROR" 
END IF 
RETRY 
END HANDLER 
END 
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Output 


Enter an integer expression? ABCD 
Error number 50 

DATA FORMAT ERROR 

Enter an integer expression? 0 
03-Aug-86 
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ERTS 


ERTS 


The ERT$ function returns explanatory text associated with an error 
number. 


Format 


str-var = ERTS (int-exp) 
Syntax Rules 


Int-exp is a VAX BASIC error number. The error number must be in the 
range 0 through 255. 


Remarks 
1. The ERT$ function can be used at any time to return the text associ- 
ated with a specified error number. 
2. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 
Example 


10 DECLARE LONG int_exp 
WHEN ERROR USE error_routine 
20 INPUT "Enter an integer expression"; int_exp 
PRINT DATE$(int_exp) 
END WHEN 
HANDLER error_routine 
PRINT "Error number"; ERR 
PRINT ERT$ (ERR) 
RETRY 
END HANDLER 
END 
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ERTS 


Output 


Enter an integer expression? ABCD 
Error number 50 

%Data format error 

Enter an integer expression? 70 
03-Feb-70 
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EXIT 


The EXIT statement lets you exit from a main program, a SUB, 
FUNCTION, or PICTURE subprogram, a multi-line DEF, a statement 
block, or a handler. 


Format 


EXIT block 


block: 


Syntax Rules 


DEF/ exp ] 
FUNCTION exp ] 
SUB 

HANDLER 

PICTURE 
PROGRAM, int-exp / 
label 


The DEF, FUNCTION, SUB, HANDLER, and PROGRAM keywords 
specify the type of subprogram, multi-line DEF, or handler from which 
VAX BASIC is to exit. 


If you specify an optional expression with the EXIT DEF statement 
or with the EXIT FUNCTION statement, the expression becomes the 
function result and supercedes any function assignment. It also over- 
rides any expression specified on the END DEF or END FUNCTION 
statement. Note that the expression must be compatible with the 
FUNCTION or DEF data type. 


Label specifies a statement label for an IF, SELECT, FOR, WHILE, or 
UNTIL statement block. 
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Remarks 


EXIT 


An EXIT SUB, EXIT FUNCTION, EXIT PROGRAM, EXIT DEF, or 
EXIT PICTURE statement is equivalent to an unconditional branch to 
an equivalent END statement. Control then passes to the statement 
that invoked the DEF or to the statement following the statement that 
called the subprogram. 


The EXIT HANDLER statement causes VAX BASIC to transfer control 
to a specified area. 


e If the current WHEN block is nested, control transfers to the 
handler associated with the next outer protected region. 

e If an ON ERROR statement is in effect and the current WHEN 
block is not nested, control transfers to the target of the ON 
ERROR statement. 

e If neither of the previous conditions is true, an EXIT HANDLER 
statement transfers control to the calling program or DCL. This 
action is the equivalent of the ON ERROR GO BACK statement. 


The EXIT PROGRAM statement causes VAX BASIC to exit from a 
main program module. 


e An optional integer expression on an EXIT PROGRAM statement 
specifies the exit status of the program that is reported to DCL. 

e The expression specified by an EXIT PROGRAM statement over- 
rides any integer expression specified by an END PROGRAM 
statement. 

e VAX BASIC allows you to specify an EXIT PROGRAM statement 
without a matching PROGRAM statement. . 

The EXIT label statement is equivalent to an unconditional branch to 

the first statement following the end of the IF, SELECT, FOR, WHILE, 

or UNTIL statement labeled by the specified label. 

An EXIT FUNCTION, EXIT SUB or EXIT PROGRAM statement cannot 

be used within a multi-line DEF function. 

When the EXIT FUNCTION, EXIT SUB or EXIT PROGRAM statement 

executes, VAX BASIC releases all storage allocated to local variables 

and returns control to the calling program. 
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EXIT 


Example 


DEF emp. bonus (A) 
IF A> 10 
THEN 
PRINT "OUT OF RANGE" 
EXIT DEF 0 
ELSE 
emp.bonus = A * 4 
END IF 
END DEF 
INPUT A 
PRINT emp. bonus (A) 
END 


Output 


? 11 
OUT OF RANGE 
0) 
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EXP 


EXP 


The EXP function returns the value of the mathematical constant e raised 
to a specified power. 


Format 


real-var = EXP (real-exp) 
Syntax Rules 
None. 
Remarks 


The EXP function returns the value of e raised to the power of real-exp. 


2. VAX BASIC expects the argument of the EXP function to be a real 
expression. When the argument is a real expression, VAX BASIC 
returns a value of the same floating-point size. When the argument is 
not a real expression, VAX BASIC converts the argument to the default 
floating-point size and returns a value of the default floating-point 
size. 


3. When the default REAL size is SINGLE or DOUBLE, EXP allows 
arguments between -88 and 88. If the default REAL size is GFLOAT, 
EXP allows arguments between —709 and 709. If the default REAL 
size is HFLOAT, the arguments can be in the range -11356 to 11355. 
When the argument exceeds the upper limit of a range, VAX BASIC 
signals an error. When the argument exceeds the lower limit of a 
range, the EXP function returns a zero and VAX BASIC does not 
signal an error. 
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EXP 


DECLARE SINGLE num_val 
num_val = EXP(4.6) 
PRINT num_val 


Output 
99.4843 
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EXTERNAL 


The EXTERNAL statement declares constants, variables, functions, and 
subroutines external to your program. You can describe parameters for 
external functions and subroutines. 


Format 


External Constants 


EXTERNAL  data-type CONSTANT const-name.... 


External Variables 


EXTERNAL  data-type unsubs-var.... 


External Functions 


EXTERNAL  data-type FUNCTION { func-name [ pass-mech ] 
[ ( external-param ,... ) ] },..- 


External Subroutines 


EXTERNAL SUB { sub-name [ pass-mech ] [ ( external-param ,...) ] },... 


BY VALUE 
pass-mech: BY REF 
BY DESC 


external-param: [OPTIONAL J [ param-data-type ] [ DIM( [,]... ) ] 
[ = int-const ] [ pass-mech ] 


External Pictures 


EXTERNAL PICTURE _pic-name [ ( param-list ) ] 
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EXTERNAL 


Syntax Rules 


For external constants, data-type can be BYTE, WORD, LONG, 
SINGLE, INTEGER (any size), or REAL (if the default size is SINGLE). 


For external variables, the data type can be any valid numeric data 
type. 

For external functions and subroutines, the data type can be BYTE, 
WORD, LONG, SINGLE, DOUBLE, GFLOAT, HFLOAT, DECIMAL, 
STRING, INTEGER, REAL, RFA, or a data type defined with the 
RECORD statement. See Table 1-2 in this manual for more informa- 
tion on data type size, range and precision. 


The name of an external constant, variable, function, or subroutine 
can be from 1 through 31 characters. 


For all external routine declarations, the name must be a valid 
VAX BASIC identifier and must not be the same as any other SUB, 
FUNCTION, PICTURE, or PROGRAM name. 


Param-data-type specifies the data type of a parameter. If you do not 
specify a data type, parameters are of the default data type and size. 


Param-list is identical to external-param except that no OPTIONAL 
parameter is allowed. 


Parameters in the param-list must agree in number and data type 
with the parameters in the invocation. Param-data-type includes ANY, 
BYTE, WORD, LONG, INTEGER, SINGLE, DOUBLE, GFLOAT, 
HFLOAT, READ, a user-defined RECORD type, STRING, or RFA. 


For more information on external pictures, see Programming with VAX 
BASIC Graphics. 
External Functions and Subroutines 


° The data type that precedes the keyword FUNCTION defines the 
data type of the function result. 


¢  Pass-mech specifies how parameters are to be passed to the 
function or subroutine. 


— A pass-mech clause outside the parentheses applies to all 
parameters. 


— A pass-mech clause inside the parentheses overrides the 
previous pass-mech and applies only to the specific parameter. 
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External-param defines the form of the arguments passed to the 
external function or subprogram. Empty parentheses indicate 
that the subprogram expects zero parameters. Missing paren- 
theses indicate that the EXTERNAL statement does not define 
parameters. 


10. Using ANY as a VAX BASIC Data Type 


The ANY data type should only be used for calling non-BASIC 
procedures. Therefore, the ANY data type is illegal in a PICTURE 
declaration. 


If you specify ANY, VAX BASIC does not perform data type 
checking or conversions. If no passing mechanism is specified, 
VAX BASIC uses the default passing mechanism for the data type 
passed in a given invocation. 


When you specify a data type, all following parameters that 

are not specifically declared default to the last specified data 
type. Similarly, when you specify ANY, all following unspecified 
parameters default to the data type ANY until a new declaration is 
provided. For example: 


EXTERNAL SUB allocate (LONG,ANY, ) 


11. Passing Optional Parameters 


The OPTIONAL keyword should be used only for calling non- 
BASIC procedures. 


If you specify the keyword OPTIONAL, VAX BASIC treats all 


following parameters as optional. In the following example, the 
last three parameters are optional. 


EXTERNAL SUB queue(STRING, OPTIONAL STRING, LONG, ANY) 


When a procedure is called, the argument pointer (@AP) contains 
the number of actual parameters specified. 


VAX BASIC still performs type checking and conversion on 
optional parameters. 


If you want to omit an optional parameter that appears in the 

middle of a parameter list, VAX BASIC requires you to insert a 
comma placeholder. However, if you want to omit an optional 
parameter that appears at the end of a parameter list, you can 

omit that parameter without inserting any placeholder. 


You can specify the keyword OPTIONAL only once in any one 
parameter list. 
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12. Declaring Array Dimensions 


The DIM keyword indicates that the parameter is an array. Commas 
specify array dimensions. The number of dimensions is equal to the 
number of commas plus 1. For example: 


EXTERNAL STRING FUNCTION new (DOUBLE, STRING DIM(,), DIM( )) 


This statement declares a function named new that has three param- 
eters. The first is a double-precision floating-point value, the second 
is a two-dimensional string array, and the third is a one-dimensional 
string array. The function returns a string result. 


Remarks 


1. The EXTERNAL statement must precede any program reference to 
the constant, variable, function, subroutine or picture declared in the 
statement. 


2. The EXTERNAL statement is not executable. 


3. A name declared in an EXTERNAL CONSTANT statement can be 
used in any nondeclarative statement as if it were a constant. 


4. A name declared in an EXTERNAL FUNCTION statement can be used 
as a function invocation in an expression. In addition, you can invoke 
a function with the CALL statement unless the function data type is 
DECIMAL, HFLOAT, or STRING. 

5. A name declared in an EXTERNAL SUB statement can be used in a 
CALL statement. 

6. The optional pass-mech clauses in the EXTERNAL FUNCTION and 
EXTERNAL SUB statements tell VAX BASIC how to pass arguments 
to a non-BASIC function or subprogram. Table 4-1 describes VAX 
BASIC parameter-passing mechanisms. 

e BY VALUE specifies that VAX BASIC passes the argument’s 32-bit 
value. 

e BY REF specifies that VAX BASIC passes the argument’s address. 
This is the default for all arguments except strings and entire 
arrays. If you know the size of string parameters and the dimen- 
sions of array parameters, you can improve run-time performance 
by passing strings and arrays by reference. 
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e BY DESC specifies that VAX BASIC passes the address of a VAX 
BASIC descriptor. For information about the format of a VAX 
BASIC descriptor for strings and arrays, see Appendix C in this 


manual. 


7. If you do not specify the data type ANY or declare parameters as 
optional, the arguments passed to external functions and subroutines 
should match the external parameters declared in the EXTERNAL 
FUNCTION or EXTERNAL SUB statement in number, type, and 
passing mechanism. VAX BASIC forces arguments to be compatible 
with declared parameters. If they are not compatible, VAX BASIC 


signals an error. 


Example 1 


!'External Constant 
EXTERNAL LONG CONSTANT SS$_NORMAL 


Example 2 


!'External Variable 
EXTERNAL WORD SYSNUM 


Example 3 


'External Function 
EXTERNAL DOUBLE FUNCTION USR$2(WORD, LONG, ANY) 


Example 4 


tExternal Subroutine 


EXTERNAL SUB calc BY DESC (STRING DIM(,), BYTE BY REF) 
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The FIELD statement dynamically associates string variables with all or 
parts of a record buffer. FIELD statements do not move data. Instead, 
they permit direct access through string variables to sections of a specified 
record buffer. 


NOTE 


The FIELD statement is supported only for compatibility with 
BASIC-PLUS. Because data defined in the FIELD statement 
can be accessed only as string data, you must use the CVTxx 
functions to process numeric data; therefore, you must convert 
string data to numeric after you move it from the record buffer. 
Then, after processing, you must convert numeric data back to 
string data before transferring it to the record buffer. DIGITAL 
recommends that you use VAX BASIC’s dynamic mapping 
feature or multiple maps instead of the FIELD statement and 
CVTxx functions. 


Format 


FIELD } #chni-exp, int-exp AS str-var[ , int-exp AS str-var ]... 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). A file must be open on the specified channel or VAX BASIC 
signals an error. 


2. Int-exp specifies the number of characters in str-var. However, a 
subsequent int-exp cannot depend on the return string from a previous 
int-exp. For example, the following statement is illegal because the 
second int-exp depends on the return string A$: 


FIELD #1%, 1% AS A$, ASCII(A$) AS BS 
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Remarks 


FIELD 


1. A FIELD statement is executable. You can change a buffer description 
at any time by executing another FIELD statement. For example: 


FIELD #1%, 40% AS whole_field$ 
FIELD #1%, 10% AS A$, 10% AS B$, 10% AS C$, 10% AS D$ 


The first FIELD statement associates the first 40 characters of a buffer 
with the variable whole_field$. The second FIELD statement associates 
the first 10 characters of the same buffer with A$, the second 10 
characters with B$, and so on. Later program statements can refer to 
any of the variables named in the FIELD statements to access specific 
portions of the buffer. 


2. You cannot define virtual array strings as string variables in a FIELD 
statement. 


3. <A variable named in a FIELD statement cannot be used in a 
COMMON or MAP statement, as a parameter in a CALL or SUB 
statement, or in a MOVE statement. , 


4. Using the FIELD statement on a virtual file that contains a virtual array 
causes VAX BASIC to signal “Illegal or illogical access” (ERR=136). 


5. If you name an array in a FIELD statement, you cannot use MAT 
statements of the format 


MAT array-namel = array-name2 


MAT array-namei = NUL$ 


where array-namel1 is named in the FIELD statement. An attempt to 
do so causes VAX BASIC to signal a compile-time error. 


FIELD #8%, 2% AS U$, 2% AS CL$, 4% AS X$, 4% AS Y$ - 
LSET U$ = CVT%$(U%) 

LSET CL$ = CVT%$(CL%) 

LSET X$ = CVTF$(X) 

LSET Y$ = CVTF$(Y) 

U% = CVT$%,(U$) 

CL% = CVT$% (CL$) 

X = CVT$F(X$) 

Y = CVT$F(Y$) 
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The FIND statement locates a specified record in a disk file and makes 
it the current record for a GET, UPDATE, or DELETE operation. FIND 
statements are valid on RMS sequential, relative, and indexed files. 


Format 


FIND #chnl-exp [ , position-clause ][ , lock-clause] 


RFA rfa-exp 
position-clause: RECORD num-exp 
KEY# key-clause 


lock-clause: WAIT [ int-exp ] 


| ALLOWallow-clause [ ,WAIT [ int-exp ] ] 
REGARDLESS 


NONE 
allow-clause: READ 


MODIFY 


key-clause: int-exp1 rel-op key-exp 


rel-op: NXEQ 
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Syntax Rules 


Remarks 


FIND 


int-exp2 
str-exp 
decimal-exp 
quadword-exp 


Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 


If you specify a lock-clause, it must follow the position-clause. If the 
lock-clause precedes the position-clause, VAX BASIC signals an error. 


If you specify the REGARDLESS lock-clause, you cannot specify 
another lock-clause in the same FIND statement. 


Position-clause 


Position-clause specifies the position of a record in a file. VAX 

BASIC signals an error if you specify a position-clause and the 

channel is not associated with a disk file. If you do not specify 
a position-clause, FIND locates records sequentially. Sequential 
record access is valid on all files. 


The RFA position-clause allows you to randomly locate records by 
specifying the record file address (RFA) of a record. You specify 
the disk address of a record, and RMS locates the record at that 
address. All file organizations can be accessed by RFA. 


Rfa-exp in the RFA position-clause is a variable of the RFA data 
type that specifies the record’s file address. Note that an RFA 
expression can only be a variable of the RFA data type or the 
GETRFA function. Use the GETRFA function to find the RFA of.a 
record. 
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The RECORD position-clause allows you to randomly locate 
records in relative and sequential fixed files by specifying the 
record number. . 


— Num-exp in the RECORD position-clause specifies the number 
of the record you want to locate. It must be between 1 and 
the number of the record with the highest number in the file. 


— When you specify a RECORD clause, chnl-exp must be a 
channel associated with an open relative or sequential fixed 
file. 

The KEY position-clause allows you to randomly locate records in 

indexed files by specifying a key of reference, a relational test, and 

a key value. 


An RFA value is valid only for the life of a specific version of 
a file. If a new version of a file is created, the RFA values may 
change. 


Attempting to access a record with an invalid RFA value results in 
a run-time error. 


2. Lock-clause 


Lock-clause allows you to control how a record is locked to other 
access streams, to override lock checking when accessing shared 

files that may contain locked records, or to specify what action to 
take in the case of a locked record. 


The type of lock you impose on a record remains in effect until 
you explicitly unlock it with a FREE or UNLOCK statement, until 
you close the file, or until you perform a GET, FIND, UPDATE 
or DELETE on the same channel (unless you specified UNLOCK 
EXPLICIT). 


The REGARDLESS lock-clause specifies that the FIND statement 
can override lock checking and locate a record locked by another 
program. 


When you specify a REGARDLESS lock-clause, VAX BASIC does 
not impose a lock on the retrieved record. 


The ALLOW lock-clause lets you control how a record is locked 
to other users and access streams. The file associated with the 
specified channel must have been opened with the UNLOCK 
EXPLICIT clause or VAX BASIC signals the error “Illegal record 
locking clause”. 
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¢ The ALLOW allow-clause can be one of the following: 


ALLOW NONE denies access to the record. This means that 
other access streams cannot retrieve the record unless they 
bypass lock checking with the GET REGARDLESS clause. 


ALLOW READ provides read access to the record. This means 
that other access streams can retrieve the record but cannot 
use the DELETE or UPDATE statements on the record. 


Statements and Functions 4-104.1 


FIND 


ALLOW MODIFY provides read and write to the record. This 
means that other access streams can use the GET, FIND, 
DELETE, and UPDATE statements on the record. 


If you do not open a file with the ACCESS READ clause or specify 
an allow-clause, locking is imposed as follows: 


If the file associated with the specified channel was opened 
with UNLOCK EXPLICIT, VAX BASIC imposes the ALLOW 
NONE lock on the retrieved record and the next GET or FIND 
operation does not unlock the previously locked record. 


If the file associated with the specified channel was not 
opened with UNLOCK EXPLICIT, VAX BASIC locks the 
retrieved record and unlocks the previously locked record. 


The WAIT lock-clause accepts an optional int-exp. Int-exp repre- 
sents a timeout value in seconds. Int-exp must be from 0 through 
255 or VAX BASIC signals a warning message. 


WAIT followed by a timeout value causes RMS to wait for a 
locked record for a given period of time. 


WAIT followed by no timeout value indicates that RMS should 
wait indefinitely for the record to become available. 


If you specify a timeout value and the record does not become 
available within that period, VAX BASIC signals the the run- 
time error “Keyboard wait exhausted” (ERR=15). VMSSTATUS 
and RMSSTATUS then return RMS$_TMO. For more infor- 
mation on the RMSSTATUS and VMSSTATUS functions, see 
this chapter and the VAX BASIC User Manual. 


If you attempt to wait for a record that another user has 
locked, and consequently that user attempts to wait for the 
record you have locked, a deadlock condition occurs. When a 
deadlock condition persists for a period of time (as defined by 
the SYSGEN parameter DEADLOCK_WAIT), RMS signals the 
error “RMS$_DEADLOCK” and VAX BASIC signals the error 
“Detected deadlock error while waiting for GET or FIND” 
(ERR=193). 


If you specify a WAIT clause followed by a timeout value that 
is less than the SYSGEN parameter DEADLOCK_WAIT, VAX 
BASIC signals the error “Keyboard wait exhausted” (ERR=15) 
even though a deadlock condition may exist. 
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3. Key-clause 


¢ Ina key-clause, int-exp1 is the target key of reference. It must be 
an integer in the range of zero through the highest-numbered key 
for the file. The primary key is #0, the first alternate key is #1, the 
second alternate key is #2, and so on. Int-exp1 must be preceded 
by a number sign (#) or VAX BASIC signals an error. 


e When you specify a key-clause, the specified channel must be a 
channel associated with an open indexed file. 


4. Rel-op 


¢  Rel-op is a relational operator that specifies how key-exp is to be 
compared with int-exp1 in the key-clause. 


— EQ means “equal to” 

— NXEQ means “next or equal to” 

— GE means “greater than or next” (a synonym for NXEQ) 
— NX means “next” 

— GT means “greater than” (a synonym for NX) 


e A successful random FIND operation by key locates the first 
record whose key satisfies the key-clause comparison: 


— With an exact key match (EQ), a successful FIND locates the 
first record in the file that equals the key value specified in 
key-exp. However, if the characters specified by a str-exp key 
expression are less than the key length, characters specified 
by str-exp are matched approximately rather than exactly. 

For example, if you specify “ABC” and the key length is six 
characters, VAX BASIC locates the first record that begins with 
ABC. If you specify “ABCABC”, VAX BASIC locates only a 
record with the key “ABCABC”. If no match is possible, VAX 
BASIC signals the error “Record not found” (ERR=155). 


— If you specify a next or equal to record key match (NXEQ), 
a successful FIND locates the next record that equals the key 
length specified in int-exp or str-exp. If no exact match exists, 
VAX BASIC locates the next record in the key sort order. If 
the keys are in ascending order, the next record will have a 
greater key value. If the keys are in descending order, the 
next record will have a lesser key value. 


— If you specify a greater than or equal to key match (GE), 
the behavior is identical to that of next or equal to (NXEQ). 
(Likewise, the behavior of GT is identical to NX.) However, 
the use of GE in a descending key file may be confusing, since 
GE will retrieve the next record in the key sort order but 
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the next record will have a lesser key value. For this reason, 
DIGITAL recommends that you use NXEQ in new program 
development, especially if you are using descending key files. 


— If you specify a next key match (NX), a successful FIND 
locates the first record that follows the relational operator in 
the sort order. If no such record exists, VAX BASIC signals the 
error “Record not found” (ERR=155). 


Key-exp 


Int-exp2 specifies an integer value to be compared with the key 
value of a record. 


Str-exp specifies a string value to be compared with the key value 
of a record. Str-exp can contain fewer characters than the key of 
the record you want to locate, but cannot be a null string. 


Decimal-exp in the key clause specifies a packed decimal value to 
be compared with the key value of a record. 


Quadword-exp in the key clause specifies a a record or group 
which is exactly 8 bytes long that is to be compared with the key 
value of a record. 


The file on the specified channel must have been opened with 
ACCESS MODIFY, ACCESS READ, or SCRATCH before your pro- 
gram can execute a FIND operation. 


FIND does not transfer any data to the record buffer. To access the 
contents of a record, use the GET statement. 


A successful sequential FIND operation updates both the current 
record pointers and next record pointers. 


For sequential files, a successful FIND operation locates the next 
sequential record (the record pointed to by the next record pointer) 
in the file, changes the current record pointer to the record just 
found, and the next record pointer to the next sequential record. 
If the current record pointer points to the last record in a file, a 
sequential FIND operation causes VAX BASIC to signal “Record 
not found” (ERR=155). 


For relative files, a successful FIND operation locates the record 
that exists with the next higher record number (or cell number), 
makes it the current record, and changes the next record pointer 
to the current record pointer plus 1. 


For indexed files, a successful FIND operation locates the next 
existing logical record in the current key of reference, makes this 
the current record and changes the next record pointer to the 
current record pointer plus 1. 
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10. 


11. 


12, 


A successful random access FIND operation by RFA or by record 
changes the current record pointer to the record specified by rfa-exp or 
int-exp, but leaves the next record pointer unchanged. 


A successful random access FIND operation by key changes the 
current record pointer to the first record whose key satisfies the 
key-clause comparison and leaves the next record pointer unchanged. 


When a random access FIND operation by RFA, record, or key is 
not successful, VAX BASIC signals “Record not found” (ERR=155). 
The values of the current record pointer and next record pointer are 
undefined. 


You should not use a FIND statement on a terminal-format or virtual 
array file. 


DECLARE LONG rec-num 
MAP (cusrec) WORD cus_num & 


OPEN "CUS_ACCT.DAT" FOR INPUT AS #1, 


STRING cus_nam=20, cus_add=20, cus_city=10, cus_zip=9 


RELATIVE FIXED, 
ACCESS MODIFY 
MAP cusrec 


Re &S 


INPUT "Which record number would you like tc delete";rec_num 
FIND #1, RECORD rec_num, WAIT 

DELETE #1 

CLOSE #1 


END 
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The FIX function truncates a floating-point value at the decimal point and 
returns the integer portion represented as a floating-point value. 


Format 


real-var = FIX (real-exp) 
Syntax Rules 
None. 
Remarks 


1. The FIX function returns the integer portion of a floating-point value, 
not an integer value. 


2. VAX BASIC expects the argument of the FIX function to be a real 
expression. When the argument is a real expression, VAX BASIC 
returns a value of the same floating-point size. When the argument is 
not a real expression, VAX BASIC converts the argument to the default 
floating-point size and returns a value of the default floating-point 
size. 


3. If real-exp is negative, FIX returns the negative integer portion. For 
example, FIX(-5.2) returns —5. 
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Example 


DECLARE SINGLE result 
result = FIX(-3.333) 
PRINT FIX(24.566), result 


Output 
24 -3 
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FNEND 


The FNEND statement is a synonym for the END DEF statement. See the 
END statement for more information. 


Format 
FNEND [exp] 
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FNEXIT 


The FNEXIT statement is a synonym for the EXIT DEF statement. See the 
EXIT statement for more information. 


Format 
FNEXIT / exp] 
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The FOR statement repeatedly executes a block of statements, while in- 
crementing a specified control variable for each execution of the statement 
block. FOR loops can be conditional or unconditional, and can modify 
other statements. 


Format 


Unconditional 
FOR num-unsubs-var = num-exp! T0 num-exp2 [ STEP num-exp3 ] 
[ statement ]... 


NEXT num-unsubs-var 


Conditional 


UNTIL 


FOR num-unsubs-var = num-exp1 [ STEP -exp3 J § 
num-unsubs-var = num-exp! [ $ num-exp3 ] WHILE 


} cond-exp 


[ statement ]... 
NEXT num-unsubs-var 


Unconditional Statement Modifier 
statement FOR num-unsubs-var = num-exp1 TO num-exp2 [ STEP num-exp3] 


Conditional Statement Modifier 


UNTIL 


tatement FOR num-unsubs-var = num-exp1 [ STEP -0xp3 ] | 
statement FOR num-unsubs-var = num-exp1 [ $ num-exp3 ] WHILE 


} cond-exp 


Statements and Functions 4-113 


FOR 


Syntax Rules 


1. Num-unsubs-var must be a numeric, unsubscripted variable. 

2. Num-unsubs-var is the loop variable. It is incremented each time the 
loop executes. 

3. In unconditional FOR loops, num-exp1 is the initial value of the loop 
variable; num-exp2 is the maximum value. 


4. In conditional FOR loops, num-exp1 is the initial value of the loop 
variable, while the cond-exp in the WHILE or UNTIL clause is the 
condition that controls loop iteration. 


5. Num-exp3 in the STEP clause is the value by which the loop variable 
is incremented after each execution of the loop. 


Remarks 


1. There is a limit to the number of inner loops you can contain within 
a single outer loop. This number varies according to the complexity 
of the loops. If you exceed the limit, VAX BASIC signals an error 
message. 


2. An inner loop must be entirely within an outer loop; the loops cannot 
overlap. 


3. You cannot use the same loop variable in nested FOR loops. For 
example, if the outer loop uses FOR I = 1 TO 10, you cannot use the 
variable I as a loop variable in an inner loop. 


The default for num-exp3 is 1 if there is no STEP clause. 


5. You can transfer control into a FOR loop only by returning from a 
function invocation, a subprogram call, a subroutine call, or an error 
handler that was invoked in the loop. 


6. The starting, incrementing, and ending values of the loop do not 
change during loop execution. 


7. The loop variable can be modified inside the FOR loop. 


8. VAX BASIC converts num-exp1, num-exp2, and num-exp3 to the data 
type of the loop variable before storing them. 


9. When an unconditional FOR loop ends, the loop variable contains the 
value last used in the loop, not the value that caused loop termination. 
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10. During each iteration of a conditional loop, VAX BASIC tests the value 
of cond-exp before it executes the loop. 


If you specify a WHILE clause and cond-exp is false (value zero), 
VAX BASIC exits from the loop. If the cond-exp is true (value 
nonzero), the loop executes again. 


If you specify an UNTIL clause and cond-exp is true (value 
nonzero), VAX BASIC exits from the loop. If the exp is false 
(value zero), the loop executes again. 


11. When FOR is used as a statement modifier, VAX BASIC executes the 
statement until the loop variable equals or exceeds num-exp2 or until 
the WHILE or UNLESS condition is satisfied. 


12. Each FOR statement must have a corresponding NEXT statement or 
VAX BASIC signals an error. (This is not the case if the FOR statement 
is used as a statement modifier.) 


Example 1 


!Unconditional 
DECLARE LONG course_num, STRING course_nam 


FOR I = 


3 TO 12 STEP 3 


INPUT "Course number"; course_num 
INPUT "Course name"; course_nam 


NEXT I 


Output 1 


Course 
Course 
Course 
Course 
Course 
Course 
Course 
Course 


number? 221 

name? Botany 

number? 231 

name? Organic Chemistry 
number? 237 

name? Life Science II 

number? 244 

name? Programming in VAX BASIC 


Example 2 


{Unconditional Statement Modifier 
DECLARE INTEGER counter 
PRINT "This is an unconditional statement modifier" FOR counter = i TO 3 


END 
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Output 2 


This is an unconditional statement modifier 
This is an unconditional statement modifier 
This is an unconditional statement modifier 


Example 3 


{Conditional Statement Modifier 
DECLARE INTEGER counter, & 
STRING my_name 
INPUT "Try and guess my name";my_name FOR counter = 1 UNTIL my_name = "VAX BASIC" 
PRINT "You guessed it!" 


Output 3 


Try and guess my name? VAX PASCAL 
Try and guess my name? VAX SCAN 
Try and guess my name? VAX BASIC 
You guessed it! 
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Format 


The FORMATS function converts an expression to a formatted string. 


str-var = FORMATS (exp, str-exp) 


Syntax Rules 


Remarks 


The rules for building a format string are the same as those for printing 
numbers with the PRINT USING statement. See the description of the 
PRINT USING statement for more information. 


DIGITAL recommends that you use compile-time constant expressions for 
string expressions whenever possible. When you do this, the VAX BASIC 
compiler compiles the string at compilation time rather than at run time, 
thus improving the performance of your code. 


DECLARE STRING result, & 
INTEGER num_exp 

num_exp = 12345 

result = FORMAT$(num_exp, "##, ###") 

PRINT result 


Output 
12,345 
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The FREE statement unlocks all records and buckets associated with a 
specified channel. 


Format 
FREE #chnl-exp 


Syntax Rules 


Chnl-exp is a numeric expression that specifies a channel number asso- 
ciated with a file. It must be immediately preceded by a number sign 


(#). 
Remarks 


The file specified by chnl-exp must be open. 
2. You cannot use the FREE statement with files not on disk. 


3. If there are no locked records or buckets on the specified channel, 
the FREE statement has no effect and VAX BASIC does not signal an 
error. 


4. The FREE statement does not change record buffers or pointers. 
Moreover, the position of the record pointers is undefined. 


5. _ After a FREE statement has executed, your program must execute a 
GET or FIND statement before a PUT, UPDATE, or DELETE statement 
can execute successfully. 
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Example 
OPEN "CUST_ACCT.DAT" FOR INPUT AS #3 


INPUT "Enter customer record number to retrieve"; cust_rec_num 
FREE #3 
GET #3 


In this example, CUST_ACCT.DAT is opened for input. The FREE state- 
ment unlocks all records associated with the specified channel contained 
in the file. Once the FREE statement successfully executes, the user can 
then obtain a record with either a FIND or GET statement. 
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FSPS 


The FSP$ function returns a string describing an open file on a specified 
channel. 


Format 


str-var = FSP$ (chnl-exp) 
Syntax Rules 


1. A file must be open on chnl-exp. 


2. The FSP$ function must come immediately after the OPEN statement 
for the file. 


Remarks 


1. Use the FSP$ function with files opened as ORGANIZATION 
UNDEFINED. Then use multiple MAP statements to interpret the 
returned data. 


2. See the VAX BASIC User Manual and the VAX Record Management 
Services Reference Manual for more information on FSP$ values. 


NOTE 


VAX BASIC supports the FSP$ function for compatibility 
with BASIC-PLUS-2. DIGITAL recommends that you use a 
USEROPEN routine to identify file characteristics. 
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10 MAP (A) STRING A = 32 
MAP (A) BYTE org, rat, WORD mrs, LONG alq, 
WORD bks_bls, num_keys,LONG mrn 
OPEN "STUDENT.DAT" FOR INPUT AS #1%, 
ORGANIZATION UNDEFINED, 
RECORDTYPE ANY, ACCESS READ 
A = FSP$(1%) 
PRINT "RMS organization = ";org 
PRINT "RMS record attributes = ";rat 
PRINT "RMS maximum record size = ";mrs 
PRINT "RMS allocation quantity = ";alq 
PRINT "RMS bucket size = ";bks_bls 
PRINT "Number of keys = ";num_keys 
PRINT "RMS maximum record number = ";mrn 


Output 


RMS organization = 2 
RMS record attributes = 
RMS maximum record size 
RMS allocation quantity 
RMS bucket size = 0 
Number of keys = 0 

RMS maximum record number = 0 


nous 
- Ol 


& 


& 
& 
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FUNCTION 


The FUNCTION statement marks the beginning of a FUNCTION subpro- 
gram and defines the subprogram’s parameters. 


Format 


FUNCTION data-type func-name [ pass-mech ] [([ formal-param ],...) ] 
[ statement ]... 


{ END FUNCTION [ exp / \ 


FUNCTIONEND / exp ] 
: BY REF } 
pass-mech. { BY DESC 


unsubs-var 
formal param: — [ data-type ] array-name ( | ical rey 


' 


[ = int-const ][ pass-mech ] 
Syntax Rules 


1. Func-name names the FUNCTION subprogram. 


2. Func-name can be from 1 through 31 characters. The first character 
must be an alphabetic character (A through Z). The remaining charac- 
ters, if present, can be any combination of letters, digits (0 through 9), 
dollar signs ($), periods (.), or underscores (_). 


3. Data-type can be any VAX BASIC data type keyword or a data type 
defined in the RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2 in this manual. 
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Remarks 


FUNCTION 


The data type that precedes the func-name specifies the data type of 
the value returned by the function. 


Formal-param specifies the number and type of parameters for the 
arguments the function expects to receive when invoked. 


e Empty parentheses indicate that the function has no parameters. 


e Data-type specifies the data type of a parameter. If you do not 
specify a data type, parameters are of the default data type and 
size. When you do specify a data type, all following parameters 
are of that data type until you specify a new data type. 


If the data type is STRING and the passing mechanism is by 
reference (BY REF), the =int-const clause allows you to specify the 
length of the string. 


e¢ Parameters defined in formal-param must agree in number and 
type with the arguments specified in the function invocation. 
VAX BASIC allows you to specify from 1 through 255 formal 
parameters. 


Pass-mech specifies the parameter-passing mechanism by which 
the FUNCTION subprogram receives arguments when invoked. A 
pass-mech clause should be specified only when the FUNCTION 
subprogram is being called by a non-BASIC program or when the 
FUNCTION receives a string or array by reference. 


A pass-mech clause outside the parentheses applies by default to 
all function parameters. A pass-mech clause in the formal-param list 
overrides the specified default and applies only to the immediately 
preceding parameter. 


Exp specifies the function result which supersedes any function assign- 
ment. Exp must be compatible with the function’s data type. 


The FUNCTION statement must be the first statement in the 
FUNCTION subprogram. 


Every FUNCTION statement must have a corresponding END 
FUNCTION or FUNCTIONEND statement. 


Any VAX BASIC statement except END, PICTURE, END PICTURE, 
PROGRAM, END PROGRAM, SUB, SUBEND, END SUB, or SUBEXIT 
can appear in a FUNCTION subprogram. 
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4. FUNCTION subprograms must be declared with the EXTERNAL 
statement before your VAX BASIC program can invoke them. 


5. FUNCTION subprograms receive parameters by reference or by 
descriptor. 


e BY REF specifies that the function receives the argument’s address. 


e BY DESC specifies that the function receives the address of a VAX 
BASIC descriptor. For information about the format of a VAX 
BASIC descriptor for strings and arrays, see the VAX BASIC User 
Manual; for information on other types of descriptors, see the VAX 
Architecture Handbook. 


6. By default, FUNCTION subprograms receive numeric unsubscripted 
variables by reference, and all other parameters by descriptor. You 
can override these defaults with a BY clause: 


e If you specify a string length with the =int-const clause, you must 
also specify BY REF. If you specify BY REF and do not specify a 
string length, VAX BASIC uses the default string length of 16. 


e If you specify array bounds, you must also specify BY REF. 


7. All variables and data, except virtual arrays, COMMON areas, MAP 
areas, and EXTERNAL variables, in a FUNCTION subprogram, are 
local to the subprogram. 


8. VAX BASIC initializes local numeric variables to zero and local string 
variables to the null string each time the FUNCTION subprogram is 
invoked. 


9. If an exception is not handled within the FUNCTION subprogram, 
control is transferred back to the main program that invoked the 
function. 


Example 


FUNCTION REAL sphere_volume (REAL R) 
IF R < O THEN EXIT FUNCTION 
Sphere_volume = 4/3 * PI *R **3 

END FUNCTION 


4-124 Statements and Functions July 1988 


FUNCTIONEND 


FUNCTIONEND 


The FUNCTIONEND statement is a synonym for the END FUNCTION 
statement. See the END statement for more information. 


Format 
FUNCTIONEND /[ exp] 


Statements and Functions 4-125 


FUNCTIONEXIT 


FUNCTIONEXIT 


The FUNCTIONEXIT statement is a synonym for the EXIT FUNCTION 
statement. See the EXIT statement for more information. 


Format 
FUNCTIONEXIT /[ exp] 


4-126 Statements and Functions 


GET 


GET 


The GET statement moves a record from a file to a record buffer and 
makes the data available for processing. GET statements are valid on 
sequential, relative, and indexed files. 


Format 


GET #chnl-exp [ , position-clause ] [ , lock-clause ] 


RFA rfa-exp 
position-clause: RECORD num-exp 
KEY# key-clause 


ALLOWallow-clause [, WAIT[ int-exp ] ] 
lock-clause: WAIT [ int-exp ] 
REGARDLESS 


NONE 
allow-clause: READ 
MODIFY 


key-clause: int-exp1 rel-op key-exp 


rel-op: NXEQ 


Statements and Functions 4-127 


GET 


key-exp 


Syntax Rules 


Remarks 


int-exp2 
Str-exp 
decimal-exp 
quadword-exp 


Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 


If you specify a lock-clause, it must follow the position-clause. If the 
lock-clause precedes the position-clause VAX BASIC signals an error. 


If you specify the REGARDLESS lock-clause, you cannot specify 
another lock-clause in the same GET statement. 


Position-clause 


Position-clause specifies the position of a record in a file. VAX 
BASIC signals an error if you specify a position-clause and chnl- 
exp is not associated with a disk file. If you do not specify a 
position-clause, GET retrieves records sequentially. Sequential 
record access is valid on all files. 


The RFA position-clause allows you to randomly retrieve records 
by specifying the record file address (RFA); you specify the disk 
address of a record, and RMS retrieves the record at that address. 
All file organizations can be accessed by RFA. 


Rfa-exp in the RFA position-clause is an expression of the RFA data 
type that specifies the record’s file address. An RFA expression 
must be a variable of the RFA data type or the GETRFA function. 
Use the GETRFA function to obtain the RFA of a record. 
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e The RECORD position-clause allows you to randomly retrieve 
records in relative and sequential fixed files by specifying the 
record number. 


— Num-exp in the RECORD position-clause specifies the number 
of the record you want to retrieve. It must be between 1 and 
the number of the record with the highest number in the file. 


— When you specify a RECORD clause, chnl-exp must be a 
channel associated with an open relative or sequential fixed 
file. 

e The KEY position-clause allows you to randomly retrieve records 
in indexed files by specifying a key of reference, a relational test, 
or a key value. 


e An RFA value is valid only for the life of a specific version of 
a file. If a new version of a file is created, the RFA values may 
change. 


e Attempting to access a record with an invalid RFA value results in 
a run-time error. 


2. Lock-clause 
e Lock-clause allows you to control how a record is locked to other 
access streams, to override lock checking when accessing shared 


files that may contain locked records, or to specify what action to 
take in the case of a locked record. 


e¢ The type of lock you impose on a record remains in effect until 
you explicitly unlock it with a FREE or UNLOCK statement, until 
you close the file, or until you perform a GET, FIND, UPDATE 
or DELETE on the same channel (unless you specified UNLOCK 
EXPLICIT). 


e The REGARDLESS lock-clause specifies that the GET statement 
can override lock checking and read a record locked by another 
program. 


e When you specify a REGARDLESS lock-clause, VAX BASIC does 
not impose a lock on the retrieved record. 


e If you specify an ALLOW lock-clause the file associated with chnl- 
exp must have been opened with the UNLOCK EXPLICIT clause 
or VAX BASIC signals the error “Illegal record locking clause”. 


e The ALLOW allow-clause can be one of the following: 


— ALLOW NONE denies access to the record. This means that 
other access streams cannot retrieve the record unless they 
bypass lock checking with the REGARDLESS clause. 
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ALLOW READ provides read access to the record. This means 
that other access streams can retrieve the record, but cannot 
DELETE or UPDATE the record. 


ALLOW MODIFY provides both read and write access to the 
record. This means that other access streams can GET, FIND, 
DELETE, or UPDATE the record. 


¢ If you do not open a file with ACCESS READ or specify an 
ALLOW lock-clause, locking is imposed as follows: 


If the file associated with chnl-exp was opened with UNLOCK 
EXPLICIT, VAX BASIC imposes the ALLOW NONE lock on 
the retrieved record and the next GET or FIND statement does 
not unlock the previously locked record. 


If the file associated with chnl-exp was not opened with 
UNLOCK EXPLICIT, VAX BASIC locks the retrieved record 
and unlocks the previously locked record. 


e¢ The WAIT lock-clause accepts an optional int-exp. Int-exp repre- 
sents a timeout value in seconds. Int-exp must be from 0 through 
255 or VAX BASIC issues a warning message. 
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WAIT followed by a timeout value causes RMS to wait for a 
locked record for a given period of time. 


WAIT followed by no timeout value indicates that RMS should 
wait indefinitely for the record to become available. 


If you specify a timeout value and the record does not become 
available within that period, VAX BASIC signals the the run- 
time error “Keyboard wait exhausted” (ERR=15). VMSSTATUS 
and RMSSTATUS then return RMS$_TMO. For more infor- 
mation on the RMSSTATUS and VMSSTATUS functions, see 
this chapter and the VAX BASIC User Manual. 


If you attempt to wait for a record that another user has 
locked, and consequently that user attempts to wait for the 
record you have locked, a deadlock condition occurs. When a 
deadlock condition persists for a period of time (as defined by 
the SYSGEN parameter DEADLOCK_WAIT), RMS signals the 
error “RMS$_.DEADLOCK” and VAX BASIC signals the error 
“Detected deadlock error while waiting for GET or FIND” 
(ERR=193). 

If you specify a WAIT clause followed by a timeout value 
that is less than the SYSGEN parameter DEADLOCK_WAIT, 


then VAX BASIC signals the error “Keyboard wait exhausted” 
(ERR=15) even though a deadlock condition may exist. 


GET 


— If you specify a WAIT clause on a GET operation to a unit 
device, the timeout value indicates how long to wait for the 
input to complete. This is equivalent to the WAIT statement. 
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3. Key-clause 


In a key-clause, int-exp1 is the target key of reference. It must be a 
integer value in the range of zero through the highest-numbered 
key for the file. The primary key is #0, the first alternate key is 
#1, the second alternate key is #2, and so on. Int-exp1 must be 
preceded by a number sign (#) or VAX BASIC signals an error. 


When you specify a key clause, chnl-exp must be a channel 
associated with an open indexed file. 


4. Rel-op 


Rel-op specifies how key-exp is to be compared with int-exp1 in the 
key-clause. 


— EQ means “equal to” 

— NXEQ means “next or equal to” 

— GE means “greater than or equal to” (a synonym for NXEQ) 
— NX means “next” 

— GT means “greater than” (a synonym for NX) 


With an exact key match (EQ), a successful GET operation re- 
trieves the first record in the file that equals the key value spec- 
ified in key-exp. If the key expression is a str-exp whose length 

is less than the key length, characters specified by the str-exp are 
matched approximately rather than exactly. That is, if you specify 
a string expression “ABC” and the key length is six characters, 
VAX BASIC matches the first record that begins with ABC. If you 
specify “ABCABC”, VAX BASIC matches only a record with the 
key “ABCABC”. If no match is possible, VAX BASIC signals the 
error “Record not found” (ERR=155). 


If you specify a next or equal to key match (NXEQ), a successful 
GET operation retrieves the first record that equals the key value 
specified in key-exp. If no exact match exists, VAX BASIC retrieves 
the next record in the key sort order. If the keys are in ascending 
order, the next record will have a greater key value. If the keys 
are in descending order, the next record will have a lesser key 
value. 


If you specify a greater than key match (GT), a successful GET 
operation retrieves the first record with a value greater than key- 
exp. If no such record exists, VAX BASIC signals the error “Record 
not found” (ERR=155). 
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e If you specify a next key match (NX), a successful GET operation 
retrieves the first record that follows the key expression in the key 
sort order. If no such record exists, VAX BASIC signals the error 
“Record not found” (ERR=155). 


e If you specify a greater than or equal to key match (GE), the 
behavior is identical to that of next or equal to (NXEQ). Likewise, 
the behavior of GT is identical to NX. However, the use of GE in 
a descending key file may be confusing, because GE will retrieve 
the next record in the key sort order but the next record will have 
a lesser key value. For this reason, DIGITAL recommends that 
you use NXEQ in new program development, especially if you are 
using descending key files. 


5. Key-exp 


e Int-exp2 in the key clause specifies an integer value to be com- 
pared with the key value of a record. 


e Str-exp in the key clause specifies a string value to be compared 
with the key value of a record. The string expression can contain 
fewer characters than the key of the record you want to retrieve 
but it cannot be a null string. 


¢ Decimal-exp in the key clause specifies a packed decimal value to 
be compared with the key value of a record. 


¢ Quadword-exp in the key clause specifies a RECORD or GROUP 
exactly 8 bytes long to be compared with the key value of a 
record. 


6. The file specified by chnl-exp must be opened with ACCESS READ or 
ACCESS MODIFY or SCRATCH before your program can execute a 
GET statement. The default ACCESS clause is MODIFY. 


7. If the last I/O operation was a successful FIND operation, a sequential 
GET operation retrieves the current record located by the FIND 
operation and sets the next record pointer to the record logically 
succeeding the pointer. 


8. If the last I/O operation was not a FIND operation, a sequential 
GET operation retrieves the next record and sets the record logically 
succeeding the record pointer to the current record. 


e For sequential files, a sequential GET operation retrieves the next 
record in the file. 


e For relative files, a sequential GET operation retrieves the record 
with the next higher cell number. 


e For indexed files, a sequential GET operation retrieves the next 
record in the current key of reference. 
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13. 


14. 


15. 


16. 


GET 


A successful random GET operation by RFA or by record retrieves the 
record specified by rfa-exp or int-exp. 

A successful random GET operation by key retrieves the first record 
whose key satisfies the key-clause comparison. 


A successful random GET operation by RFA, record, or key sets the 
value of the current record pointer to the record just read. The next 
record pointer is set to the next logical record. 


An unsuccessful GET operation leaves the record pointers and the 
record buffer in an undefined state. 


If the retrieved record is smaller than the receiving buffer, VAX BASIC 
fills the remaining buffer space with nulls. 


If the retrieved record is larger than the receiving buffer, VAX BASIC 
truncates the record and signals an error. 


A successful GET operation sets the value of the RECOUNT variable 
to the number of bytes transferred from the file to the record buffer. 


You should not use a GET statement on a terminal-format or virtual 
array file. 


DECLARE LONG rec-num 


MAP (CUSREC) WORD cus_num & 
STRING cus_nam = 20, cus_add = 20, cus_city = 10, cus_zip = 9 
OPEN "CUS_ACCT.DAT" FOR INPUT AS #1 & 
RELATIVE FIXED, ACCESS MODIFY, & 
MAP CUSREC 


INPUT "Which record number would you like to view" ;rec_num 
GET #1, RECORD REC_NUM, REGARDLESS 

PRINT "The customer's number is ";CUS_NUM 

PRINT "The customer's name is ";cus_nam 

PRINT "The customer's address is ";cus_add 

PRINT "The customer's city is ";cus_city 

PRINT "The customer's zip code is ";cus_zip 

CLOSE #1 

END 
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GETRFA 


The GETRFA function returns the record’s file address (RFA) of the last 
record accessed in an RMS file open on a specified channel. 


Format 


rfa-var = GETRFA (chnl-exp) 


Syntax Rules 


Remarks 


Rfa-var is a variable of the RFA data type. 


Chnl-exp is the channel number of an open RMS file. You cannot 
include a number sign in the channel expression. 


You must access a record in the file with a GET, FIND, or PUT 


statement before using the GETRFA function, or VAX BASIC signals 
“No current record” (ERR=131). 


There must be a file open on the specified chnl-exp or VAX BASIC 
signals an error. 

You can use the GETRFA function with RMS sequential, relative, 
indexed, and block I/O files. 

The RFA value returned by the GETRFA function can be used only 
for assignments to and comparisons with other variables of the RFA 
data type. Comparisons are limited to equal to (=) and not equal to 
( < > ) relational operations. 


RFA values cannot be printed or used for any arithmetic operations. 
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Example 
DECLARE RFA R_ARRAY(1i TO 100) 


FOR I% = 1% TO 100% 

PUT #1 

R_ARRAY(1%,) = GETRFA(1) 
NEXT 1% 


GETRFA 
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The GOSUB statement transfers control to a specified line number or label 
and stores the location of the GOSUB statement for eventual return from 
the subroutine. 


Format 
GO SUB 
target 
{ GOsuB : 
Syntax Rules 
1. Target must refer to an existing line number or label in the same 
program unit as the GOSUB statement or VAX BASIC signals an error. 
2. Target cannot be inside a block structure such as a FOR...NEXT, 
WHILE, or UNTIL loop or a multi-line function definition unless the 
GOSUB statement is also within that block or function definition. 
Remarks 
1. You can use the GOSUB statement from within protected regions of a 
WHEN block. GOSUB statements can also contain protected regions 
themselves. 
2. If you fail to handle an exception that occurs while a statement 


contained in the body of a subroutine is executing, the exception is 
handled by the default error handler. The exception is not handled 
by any WHEN block surrounding the statement that invoked the 
subroutine. 
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Example 
GOSUB subroutine_1 
subroutine_1i: 


RETURN 
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GOTO 


The GOTO statement transfers control to a specified line number or label. 


Format 
{coro} 


Syntax Rules 


Remarks 


target 


Target must refer to an existing line number or label in the same 
program unit as the GOTO statement or VAX BASIC signals an error. 


Target cannot be inside a block structure such as a FOR...NEXT, 
WHILE, or UNTIL loop or a multi-line function definition unless the 
GOTO statement is also inside that loop or function definition. 


You can specify the GOTO statement inside a WHEN block if the 
target is in the same protected region, an outer level protected region, 
or in a nonprotected region. 

You cannot specify the GOTO statement inside a WHEN block if the 


target already resides in another protected region that does not contain 
the innermost current protected region. 
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Example 


IF answer = 0 
THEN GOTO done 
END IF 


done: 
EXIT PROGRAM 


Statements and Functions 


GOTO 


4-139 


HANDLER 


HANDLER 


The handler statement marks the beginning of a detached handler. 


Format 
HANDLER handler-name 


Syntax Rules 


Handler-name must be a valid VAX BASIC identifier and must not be the 
same as any label, DEF, DEF*, SUB, FUNCTION or PICTURE name. 


Remarks 


1. A detached handler must be delimited by a HANDLER statement and 
an END HANDLER statement. 


2. A detached handler can be used only with VAX BASIC’s exception- 
handling mechanism. If you attempt to branch into a detached 
handler for example with the GOTO statement, VAX BASIC signals a 
compile-time error. 


3. To exit from a detached handler, you must use either END HANDLER, 
EXIT HANDLER, RETRY or CONTINUE. See these statements for 
more information. 


4. Within a handler, VAX BASIC allows you to specify user-defined 
function references and procedure invocations as well as VAX BASIC 
statements. 


5. The following statements are illegal inside a handler: 
e EXIT PROGRAM, FUNCTION, SUB, or PICTURE 
¢ GOTO to a target outside the handler 
e GOSUB to a target outside the handler 
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e ON ERROR 
¢ RESUME 


Example 
WHEN ERROR USE err_handler 


END WHEN 
HANDLER err_handler 
IF ERR = 50 THEN PRINT “Insufficient data" 
RETRY 
ELSE EXIT HANDLER 
END IF 
END HANDLER 


HANDLER 
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IF 


The IF statement evaluates a conditional expression and transfers program 
control depending on the resulting value. 


Format 


Conditional 


IF cond-exp THEN statement... [ ELSE statement...] 


END IF 


Statement Modifier 


statement IF cond-exp 


Syntax Rules 


1. Conditional 


Cond-exp can be any valid conditional expression. 


All statements between the THEN keyword and the next ELSE, 
line number, or END IF are part of the THEN clause. All state- 
ments between the keyword ELSE and the next line number or 
END IF are part of the ELSE clause. 


VAX BASIC assumes a GOTO statement when the keyword 
ELSE is followed by a line number. When the target of a GOTO 
statement is a label, the keyword GOTO is required. The use of 
this syntax is not recommended for new program development. 


The END IF statement terminates the most recent unterminated IF 
statement. 


A new line number terminates all unterminated IF statements. 


2. Statement Modifier 


IF can modify any executable statement except a block statement 
such as FOR, WHILE, UNTIL, or SELECT. 


Cond-exp can be any valid conditional expression. 
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Remarks 


IF 


Conditional 


VAX BASIC evaluates the conditional expression for truth or 
falsity. If true (nonzero), VAX BASIC executes the THEN clause. 
If false (zero), VAX BASIC skips the THEN clause and executes 
the ELSE clause, if present. 


The keyword NEXT cannot be in a THEN or ELSE clause unless 
the FOR or WHILE statement associated with the keyword NEXT 
is also part of the THEN or ELSE clause. 


If a THEN or ELSE clause contains a block statement such as a 
FOR, SELECT, UNTIL, or WHILE, then a corresponding block 
termination statement such as a NEXT or END, must appear in 
the same THEN or ELSE clause. 


IF statements can be nested to 12 levels. 


Any executable statement is valid in the THEN or ELSE clause, 
including another IF statement. You can include any number of 
statements in either clause. 


Execution continues at the statement following the END IF or 
ELSE clause. If the statement does not contain an ELSE clause, 
execution continues at the next statement after the THEN clause. 


Statement Modifier 


VAX BASIC executes the statement only if the conditional expres- 
sion is true (nonzero). 
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i 


IF Update_flag = True 


THEN 
Weekly_salary = New_rate * 40.0 
UPDATE #1 
IF Dept <> New_dept 
THEN 
GET #1, KEY #1 EQ New_dept 
Dept_employees = Dept_employees + 1 
UPDATE #1 
END IF 
PRINT "Update complete" 
ELSE 
PRINT “Skipping update for this employee" 
END IF 
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INKEYS 


The INKEY$ function reads a single keystroke from a terminal opened on 
a specified channel and returns the typed character. 


Format 


string-var = INKEY$ (chnl-exp [ ,WAIT [ int-exp ] J) 
Syntax Rules 


Chnl-exp must be the channel number of a terminal. 


2. Int-exp represents the timeout value in seconds and must be from 0 
through 255. Values beyond this range cause VAX BASIC to signal a 
compile-time or run-time error. 


Remarks 


1. Before using the INKEY$ function, specify the DCL command SET 
TERMINAL/HOSTSYNC. This command controls whether the system 
can synchronize the flow of input from the terminal. If you specify 
SET TERMINAL/HOSTSYNCG, the system generates a CTRL/S or a 
CTRL/Q to enable or disable the reception of input. This prevents the 
typeahead buffer from overflowing. If you do not use this command 
and the typeahead buffer overflows, VAX BASIC signais the error 
“Data overflow” (ERR=289). 


2. Before using the INKEY$ function on a VT200-series terminal, set your 
terminal to VT200 mode with 7 bit controls. 


3. Before using the INKEY$ function, either your terminal or VMS, but 
not both, must enable screen wrapping. To enable terminal screen 
wrapping, use the Set-Up key on your terminal’s keyboard to set 
the terminal to Auto Wrap. Then disable VMS screen wrapping by 
entering the DCL SET TERMINAL /NOWRAP command. To enable 
VMS screen wrapping, enter the DCL SET TERMINAL /WRAP 
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command. Then disable terminal screen wrapping by using the 
Set-Up key to set the terminal to No Auto Wrap. 


4. The INKEY$ function behaves as if the terminal were in 
APPLICATION_KEYPAD mode. 


5. If the channel is not open, VAX BASIC signals the error “I/O, channel 
not open” (ERR=9). If a file or a device other than a terminal is 
open on the channel, VAX BASIC signals the error “Illegal operation” 
(ERR=141). 


6. The optional WAIT clause specifies a timeout interval during which 
the command will await terminal input. If you specify WAIT int-exp, 
the timeout period will be the specified number of seconds. If you 
specify a WAIT clause followed by no timeout value, VAX BASIC 
waits indefinitely for terminal input. 


7. VAX BASIC always examines the typeahead buffer first and retrieves 
the next keystroke in the buffer if the buffer is not empty. If the 
typeahead buffer is empty and an optional WAIT clause was specified, 
VAX BASIC waits for a keystroke to be typed for the specified timeout 
interval (indefinitely if WAIT was specified with no timeout interval). 
If the typeahead buffer is empty, and the waiting period is either not 
specified or expired, VAX BASIC returns the error message “Keyboard 
wait exhausted” (ERR=15). 


8. The escape character (ASCII code 27) is not valid as INKEY$ input. 
If you enter an escape character, normal program execution resumes 
when the INKEY$ times out. Without a specified timeout value, the 
program execution cannot resume without error. 


9. VAX BASIC returns the error message “Keyboard wait exhausted” 
(ERR=15) when any key is pressed after the escape character if no 
timeout is specified or if the specified timeout has not yet occurred. 

10. INKEY$ turns off all line editing. As a result, control of all line-editing 
characters and the arrow keys is passed back to the user. . 

11. Non-editing characters normally intercepted by the VAX/VMS ter- 
minal driver are not returned. These include the CTRL/C, CTRL/Y, 
CTRL/S, CTRLY/O characters (unless CTRL/C trapping is enabled). 
They are handled by the device driver just as in normal input. 

12. All ASCII characters are returned in a 1-byte string. 


13. All keystrokes that result in an escape sequence are translated to 
mnemonic strings based on the following key names: 


e PF1-PF4 
e E1-E6 
© F7-F20 
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INKEYS 


LEFT 
RIGHT 
UP 
DOWN 
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Example 


INKEYS 


e KPO to KP9 
e Kp- 

e  =6KP, 

e  =6KP. 

e ENTER 


PROGRAM Inkey_demo 


DECLARE STRING KEYSTROKE 


Inkey_Loop: 
WHILE 1% 


KEYSTROKE = INKEY$(0%, WAIT) 


SELECT KEYSTROKE 


CASE 


CASE 


CASE 


CASE 


CASE 


CASE 


CASE 


CASE 


'26'C 

PRINT "CTRL/Z to exit" 

EXIT Inkey_Loop 

CR,LF,VT,FF,ESC 

PRINT "Line terminator" 

"PFi" TO "PF4" 

PRINT "P function key" 

"ei" TO "E6" , aPp7s TO "FQ", "Eio" To "F20" 
PRINT "VT200 function key" 

"KPO" TO "KP9" 

PRINT “Application keypad key" 

< SP 

PRINT "Control character" 

'127'C 

PRINT "<DEL>" 

ELSE 

PRINT 'Character is "'; KEYSTROKE; ‘"' 


END SELECT 


NEXT 


END PROGRAM 
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INPUT 


The INPUT statement assigns values from your terminal or from a 
terminal-format file to program variables. 


Format 


INPUT [ #chnil-exp, ] [ str-const1 { } ] var1 [ { } [ str-const2 { \ ] var2 J... 


a tl 
. . 
' ' 


Syntax Rules 


1. You must supply an argument to the INPUT statement. Otherwise, 
VAX BASIC signals an error message. 


2. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 

3. You can include more then one string constant in an INPUT statement. 
Str-const1 is issued for str-varl, str-const2 for str-var2, and so on. 


4. Str-varl1 and str-var2 cannot be a DEF function names unless the 
INPUT statement is inside the multi-line DEF that defines the func- 
tion. 


5. The separator (comma or semicolon) that directly follows str-varl and 
str-var2 has no formatting effect. VAX BASIC always advances to a 
new line when you terminate input with a carriage return. 


6. The separator that directly follows str-const1 and str-const2, determines 
where the question mark prompt (if requested) is displayed and where 
the cursor is positioned for input. 


A comma causes VAX BASIC to skip to the next print zone and 
display the question mark unless a SET NO PROMPT statement has 
been executed. For example: 


DECLARE STRING your_name 
INPUT "What is your name", your_name 
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Remarks 


INPUT 


Output 


What is your name ? 


A semicolon causes VAX BASIC to display the question mark next to 
str-const unless a SET NO PROMPT statement has been executed. For 
example: 


DECLARE STRING your_name 
INPUT "What is your name"; your_name 


Output 


What is your name? 


VAX BASIC always advances to a new line when you terminate input 
with a carriage return. 


If you do not specify a channel, the default chnl-exp is #0 (the con- 
trolling terminal). If a chnl-exp is specified, a file must be open on that 
channel with ACCESS READ or MODIFY before the INPUT statement 
can execute. 


If input comes from a terminal, VAX BASIC displays the contents 
of str-const1, if present. If the terminal is open on channel #0, VAX 
BASIC also displays a question mark (?). 


You can disable the question mark prompt by using the SET NO 
PROMPT statement. See the SET PROMPT statement for more 
information. 


When VAX BASIC receives a line terminator or a complete record, it 
checks each data element for correct data type and range limits, then 
assigns the values to the corresponding variables. 


If you specify a string variable to receive the input text, and the user 
enters an unquoted string in response to the prompt, VAX BASIC 
ignores the string’s leading and trailing spaces and tabs. An unquoted 
string cannot contain any commas. 


If there is not enough data in the current record or line to satisfy the 
variable list, VAX BASIC takes one of the following actions: 


e If the input device is a terminal and you have not specified SET 
NO PROMPT, VAX BASIC repeats the question mark but not the 
str-const, on a new line until sufficient data is entered. 
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INPUT 


e If the input device is not a terminal, VAX BASIC signals “Not 
enough data in record” (ERR=59). 


7. If there are more data items than variables in the INPUT response, 
VAX BASIC ignores the excess. 


8. If there is an error while data is being converted or assigned (for 
example, string data being assigned to a numeric variable), VAX 
BASIC takes one of the following actions: 


e If there is no error handler in effect and the input device is a 
terminal, VAX BASIC signals a warning, reexecutes the INPUT 
statement, and displays str-const and the input prompt. 


e If there is an error handler in effect and the input device is not a 
terminal, VAX BASIC signals “Illegal number” (ERR=52) or “Data 
format error” (ERR=50). 


9. When a RETRY, CONTINUE or RESUME statement transfers control 
to an INPUT statement, the INPUT statement retrieves a new record 
or line regardless of any data left in the previous record or line. 


10. After a successful INPUT statement, the RECOUNT variable contains 
the number of characters transferred from the file or terminal to the 
record buffer. 


11. If you terminate input text with CTRL/Z, VAX BASIC assigns the 
value to the variable and signals “End of file on device” (ERR=11) 
when the next terminal input statement executes. If you are in the 
BASIC environment and there is no subsequent INPUT, INPUT LINE, 
or LINPUT statement in the program, the CTRL/Z is passed to VAX 
BASIC as a signal to exit the BASIC environment. VAX BASIC signals 
“Unsaved changes have been made, CTRL/Z or EXIT to exit” if you 
have made changes to your program or are running a program that 
has never been saved. If you have not made changes, VAX BASIC 
exits from the BASIC environment and does not signal an error. 


DECLARE STRING var_i, & 
INTEGER var_2 
INPUT "The first variable";var_1, "The second variable"; var_2 


Output 


The first variable? name 
The second variable? 4 
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INPUT LINE 


The INPUT LINE statement assigns a string value (including the line 
terminator in some cases) from a terminal or terminal-format file to a 
string variable. 


Format 


INPUT LINE [#chnl-exp, ][ str-const! { ! ] str-varl 


J 
ry 
' 


[ statement ]...[ \ [ str-const2 | : ] str-var2 J... 


' 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 

2. Str-varl1 or str-var2 cannot be a DEF function name unless the INPUT 
LINE statement is inside the multi-line DEF that defines the function. 


3. You can include more than 1 string constant in an INPUT LINE 
statement. Str-const1 is issued for str-var1, str-const2 for str-var2, and 
so on. 


4. The separator (comma or semicolon) that directly follows str-varl and 
str-var2 has no formatting effect. VAX BASIC always advances to a 
new line when you terminate input with a carriage return. 


5. The separator that directly follows str-const1 and str-const2 determines 
where the question mark (if requested) is displayed and where the 
cursor is positioned for input. Specifically: 


e A comma causes VAX BASIC to skip to the next print zone and 
display the question mark unless a SET NO PROMPT statement 
has been executed. For example: 


DECLARE STRING your_name 
INPUT LINE "Name", your_name 
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Output 


Name ? 


e A semicolon causes VAX BASIC to display the question mark 
next to str-const unless a SET NO PROMPT statement has been 
executed. For example: 


DECLARE STRING your_name 
INPUT LINE "Name"; your_name 


Output 


Name? 


6. VAX BASIC always advances to a new line when you terminate input 
with a carriage return. 


Remarks 


1. The default chnl-exp is #0 (the controlling terminal). If a channel is 
specified, a file must be open on that channel with ACCESS READ 
before the INPUT LINE statement can execute. 


2. VAX BASIC signals an error if the INPUT LINE statement has no 
argument. 


3. If input comes from a terminal, VAX BASIC displays the contents of 
str-const1, if present. If the terminal is open on channel #0, 
VAX BASIC also displays a question mark (?). 


4. You can disable the question mark prompt by using the SET NO 
PROMPT statement. See the SET PROMPT statement for more 
information. 


5. The INPUT LINE statement assigns all input characters to string 
variables. In addition, the INPUT LINE statement places the following 
line terminator characters in the assigned string if they are part of the 
string value: 
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Hex code 
OA 

OB 

0C 

0D 

ODOA 

1B 


ASCII char 
LF 

VT 

FF 

CR 

CRLF 

ESC 


INPUT LINE 


Character name 

Line Feed 

Vertical Tab 

Form Feed 

Carriage Return 

Carriage Return/Line Feed 


Escape 


Any other line terminator, such as CRTL/D and CTRL/F when line 
editing is turned off, is not included in the assigned string. 


6. When a RETRY, CONTINUE or RESUME statement transfers control 
to an INPUT LINE statement, the INPUT LINE statement retrieves a 
new record or line regardless of any data left in the previous record or 


line. 


7. After a successful INPUT LINE statement, the RECOUNT variable 
contains the number of characters transferred from the file or terminal 
to the record buffer. 


July 1988 
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8. If you terminate input text with CTRL/Z, VAX BASIC assigns the 
value to the variable and signals “End of file on device” (ERR=11) 
when the next terminal input statement executes. If you are in the 
BASIC environment and there is no next INPUT, INPUT LINE, or 
LINPUT statement in the program, the CTRL/Z is passed to VAX 
BASIC as a signal to exit the BASIC environment. VAX BASIC signals 
“Unsaved changes have been made, CTRL/Z or EXIT to exit” if you 
have made changes to your program. If you have not made changes, 
VAX BASIC exits from the BASIC environment and does not signal an 
error. 


DECLARE STRING Z,N,record_string 
INPUT LINE "Type two words", Z$,'Type your name' ;N$ 
INPUT LINE #4%, record_string$ 
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INSTR 


The INSTR function searches for a substring within a string. It returns the 
position of the substring’s starting character. 


Format 


int-var = INSTR (int-exp, str-exp1, str-exp2) 
Syntax Rules 


1. Int-exp specifies the character position in the main string at which 
VAX BASIC starts the search. 


2. Str-exp1 specifies the main string. 
3. Str-exp2 specifies the substring. 


Remarks 


1. The INSTR function searches str-exp1, the main string, for the first 
occurrence of a substring, str-exp2, and returns the position of the 
substring’s first character. 


2. INSTR returns the character position in the main string at which VAX 
BASIC finds the substring, except in the following situations: 


e If only the substring is null, and if int-exp is less than or equal to 
zero, INSTR returns a value of 1. 


e If only the substring is null, and if int-exp is equal to or greater 
than 1 and less than or equal to the length of the main string, 
INSTR returns the value of int-exp. 


e If only the substring is null, and if int-exp is greater than the 
length of the main string, INSTR returns the main string’s length 
plus 1. 


e If the substring is not null, and if int-exp is greater than the length 
of the main string, INSTR returns a value of zero. 
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Example 


INSTR 


e If only the main string is null, INSTR returns a value of zero. 


e If both the main string and the substring are null, INSTR returns a 
1. 


3. If VAX BASIC cannot find the substring, INSTR returns a value of 
zero. 


4. If int-exp does not equal 1, VAX BASIC still counts from the beginning 
of the main string to calculate the starting position of the substring. 
That is, VAX BASIC counts character positions starting at position 1, 
regardless of where you specify the start of the search. For example, 
if you specify 10 as the start of the search and VAX BASIC finds the 
substring at position 15, INSTR returns the value 15. 


5. If int-exp is less than 1, VAX BASIC assumes a starting position of 1. 


6. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


DECLARE STRING alpha, & 
INTEGER result 

alpha = "ABCDEF" 

result = INSTR(1,alpha, "DEF") 

PRINT result 


Output 
4 
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INT 


The INT function returns the floating-point value of the largest whole 
number less than or equal to a specified expression. 


Format 


real-var =\NT (real-exp) 
Syntax Rules 


VAX BASIC expects the argument of the INT function to be a real ex- 
pression. When the argument is a real expression, VAX BASIC returns 

a value of the same floating-point size. When the argument is not a real 
expression, VAX BASIC converts the argument to the default floating-point 
size and returns a value of the default floating-point size. 


Remarks 


If real-exp is negative, VAX BASIC returns the largest whole number less 
than or equal to real-exp. For example, INT(-5.3) is -6. 


Examples 


Example 1 
DECLARE SINGLE any_nun, result 
any_num = 6.667 


result = INT(any_num) 
PRINT result 


Output 1 
6 
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Example 2 


!This example contrasts the INT and FIX functions 
DECLARE SINGLE test_nun 

test_num = -32.7 

PRINT "INT OF -32.7 IS: "; INT(test_num) 

PRINT "FIX OF -32.7 IS: "; FIX(test_num) 


Output 2 


INT OF -32.7 IS: -33 
FIX OF -32.7 IS: -32 
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INTEGER 


INTEGER 


The INTEGER function converts a numeric expression or numeric string to 
a specified or default INTEGER data type. 


Format 


, BYTE 
int-var = INTEGER (exp ; worD | 


, LONG 


Syntax Rules 


Exp can be either numeric or string. A string expression can contain the 
ASCII digits 0 through 9, a plus sign (+), or a minus sign (-—). 


Remarks 


1. VAX BASIC evaluates exp, then converts it to the specified INTEGER 
size. If you do not specify a size, VAX BASIC uses the default 
INTEGER size. 


2. If exp is a string, VAX BASIC ignores leading and trailing spaces and 
tabs. 


3. The INTEGER function returns a value of zero when a string argument 
contains only spaces and tabs, or when it is null. 


4. The INTEGER function truncates the decimal portion of REAL and 
DECIMAL numbers. 
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INPUT "Enter a floating-point number"; F_P 
PRINT INTEGER(F_P, WORD) 


Output 


Enter a floating-point number? 76.99 
76 


INTEGER 
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ITERATE 


The ITERATE statement allows you to explicitly reexecute a loop. 


Format 
ITERATE [ label ] 


Syntax Rules 


1. Label is the label of the first statement of a FOR...NEXT, WHILE, or 
UNTIL loop. 


2. Label must conform to the rules for naming variables. 
Remarks 


1. ITERATE is equivalent to an unconditional branch to the current loop’s 
NEXT statement. If you supply a label, ITERATE transfers control to 
the NEXT statement in the specified loop. If you do not supply a 
label, ITERATE transfers control to the current loop’s NEXT statement. 


2. The ITERATE statement can be used only within a FOR...NEXT, 
WHILE, or UNTIL loop. 
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ITERATE 


Example 


WHEN ERROR IN 

Date_loop: WHILE 1% = 1% 
GET #1 
ITERATE Date_loop IF Day$ <> Today$ 
ITERATE Date_loop IF Month$ <> This_month$ 
ITERATE Date_loop IF Year$ <> This_year$ 
PRINT Item$ 


NEXT 
USE 
IF ERR = 11 
THEN 
CONTINUE DONE 
ELSE 
EXIT HANDLER 
END IF 
END WHEN 
Done: END 
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KILL 


KILL 


The KILL statement deletes a disk file, removes the file’s directory entry, 
and releases the file’s storage space. 


Format 


KILL file-spec 
Syntax Rules 


File-spec can be a quoted string constant, a string variable, or a string 
expression. It cannot be an unquoted string constant. 


Remarks 
1. The KILL statement marks a file for deletion but does not delete the 
file until all users have closed it. 
2. If you do not specify a complete file specification, VAX BASIC uses the 
default device and directory. If you do not specify a file version, VAX 
BASIC deletes the highest version of the file. 
3. The file must exist, or VAX BASIC signals an error. 
4. You can delete a file in another directory if you have access to that 
directory and privilege to delete the file. 
Example 


KILL "TEMP.DAT" 
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LBOUND 


The LBOUND function returns the lower bounds of a compile-time or 
run-time dimensioned array. 


Format 


num-var = LBOUND (array-name [ , num-exp J) 
Syntax Rules 


1. Array-name must specify an array that has been either explicitly or 
implicitly declared. 


2. Num-exp specifies the number of the dimension for which you have 
requested the lower bound. 


Remarks 


1. If you do not specify a dimension, VAX BASIC automatically returns 
the lower bounds of the first dimension. 


2. If you specify a numeric expression that is less than or equal to zero, 
VAX BASIC signals an error. 


3. If you specify a numeric expression that exceeds the number of 
dimensions, VAX BASIC signals an error. 
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DECLARE INTEGER CONSTANT B = 5 


DIM A(B) 
account_num = 1 
FOR dim_num = LBOUND (A) TO 5 


A(dim_num) = account_num 
account_num = account_num + 1 
PRINT A(dim_num) 

NEXT dim_nun 


Output 


QnrPwne 


4-164 Statements and Functions 


LEFTS 


LEFTS 


The LEFT$ function extracts a specified substring from a string’s left side, 
leaving the main string unchanged. 


Format 


str-var = LEFT[$] (str-exp, int-exp) 
Syntax Rules 


1. Int-exp specifies the number of characters to be extracted from the left 
side of str-exp. 


2. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


Remarks 


1. The LEFT$ function extracts a substring from the left of the specified 
str-exp and stores it in str-var. 


2. If int-exp is less than 1, LEFT$ returns a null string. 


3. If int-exp is greater than the length of str-exp, LEFT$ returns the entire 
string. 
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Example 


DECLARE STRING sub_string, main_string 
Main_string = "1234567" 

sub_string = LEFT$(main_string, 4) 
PRINT sub_string 


Output 
1234 
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LEN 


The LEN function returns an integer value equal to the number of charac- 
ters in a specified string. 


Format 


int-var = LEN (str-exp) 
Syntax Rules 
None. 
Remarks 


1. If str-exp is null, LEN returns a value of zero. 


2. The length of str-exp includes leading, trailing, and embedded blanks. 
Tabs in str-exp are treated as a single space. 


3. The value returned by the LEN function is a LONG integer. 
Example 


DECLARE STRING alpha, & 

INTEGER length 
alpha = "ABCDEFG" 
length = LEN(alpha) 
PRINT length 


Output 
7 
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LET 


The LET statement assigns a value to one or more variables. 


Format 


[LET] var,... = exp 
Syntax Rules 


1. Var cannot be a DEF or FUNCTION name unless the LET statement 
occurs inside that DEF block or in that FUNCTION subprogram. 


2. The keyword LET is optional. 
Remarks 


1. You cannot assign string data to a numeric variable or unquoted 
numeric data to a string variable. 


2. The value assigned to a numeric variable is converted to the variable’s 
data type. For example, if you assign a floating-point value to an 
integer variable, VAX BASIC truncates the value to an integer. 


3. For dynamic strings, the destination string’s length equals the source 
string’s length. 


4. When you assign a value to a fixed-length string variable (a variable 
declared in a COMMON, MAP, or RECORD statement), the value is 
left-justified and padded with spaces or truncated to match the length 
of the string variable. 
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LET 


DECLARE STRING alpha, & 

INTEGER length 
LET alpha = "ABCDEFG" 
LET length = LEN(alpha) 
PRINT length 


Output 
7 
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LINPUT 


The LINPUT statement assigns a string value, without line terminators, 
from a terminal or terminal-format file to a string variable. 


Format 


LINPUT [ #chnl-exp, ] [ str-const! {! \ J strvart ae \ [ strconst2 | ‘ } ] 


str-var2 J... 
Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 

2. Str-varl and str-var2 cannot be DEF function names unless the 
LINPUT statement is inside the multi-line DEF that defines the 
function. 


3. You can include more than one string constant in a LINPUT statement. 
Str-const1 is issued for str-var1, str-const2 for str-var2, and so on. 


4. The separator (comma or semicolon) that directly follows str-var1 and 
str-var2 has no formatting effect. VAX BASIC always advances to a 
new line when you terminate input with a carriage return. 


5. The separator character that directly follows str-const1 and str-const2 
determines where the question mark (if requested) is displayed and 
where the cursor is positioned for input. 


e A comma causes VAX BASIC to skip to the next print zone to 
display the question mark unless a SET NO PROMPT statement 
has been executed. For example: 


DECLARE STRING your_name 
LINPUT "Name", your_name 
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Remarks 


LINPUT 


Output 


Name ? 


e A semicolon causes VAX BASIC to display the question mark 


next to str-const unless a SET NO PROMPT statement has been 
executed. For example: 


DECLARE STRING your_name 
LINPUT "What is your name"; your_name 


Output 


What is your name? 


VAX BASIC always advances to a new line when you terminate input 
with a carriage return. 


The default chnl-exp is #0 (the controlling terminal). If you specify a 
channel, the file associated with that channel must have been opened 
with ACCESS READ or MODIFY. 


VAX BASIC signals an error if the LINPUT statement has no argu- 
ment. 


If input comes from a terminal, VAX BASIC displays the contents 
of str-const1, if present. If the terminal is open on channel #0, VAX 
BASIC also displays a question mark (?). 


You can disable the question mark prompt by using the SET NO 
PROMPT statement. See the SET PROMPT statement for more 
information. 


The LINPUT statement assigns all characters, except any line termi- 
nator’s to str-varl and str-var2. Single and double quotation marks, 
commas, tabs, leading and trailing spaces, or other special characters 
in the string are part of the data. 

If the RETRY, CONTINUE or RESUME statement transfers control to 


a LINPUT statement, the LINPUT statement retrieves a new record 
regardless of any data left in the previous record. 


After a successful LINPUT statement, the RECOUNT variable contains 
the number of bytes transferred from the file or terminal to the record 
buffer. 
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8. If you terminate input text with CTRL/Z, VAX BASIC assigns the 
value to the variable and signals “End of file on device” (ERR=11) 
when the next terminal input statement executes. If you are in the 
BASIC environment and there is no next INPUT, INPUT LINE, or 
LINPUT statement in the program, the CTRL/Z is passed to VAX 
BASIC as a signal to exit the BASIC environment. 


DECLARE STRING last_name 
LINPUT "ENTER YOUR LAST NAME";Last_name 
LINPUT #2%, Last_name 
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The LOC function returns either a longword integer specifying the virtual 
address of a simple or subscripted variable, or the address of an external 
function or subprogram. For dynamic strings, the LOC function returns 
the address of the descriptor rather than the address of the data. 


Format 
‘ Var 
int-var = LOC ; } 
( ext-routine } 
Syntax Rules 
Var can be any local or external, simple or subscripted variable. 
2. Var cannot be a virtual array element. 
3. Ext-routine can be the name of external function or subprogram. 
Remarks 


1. The LOC function always returns a LONG value. 


The LOC function is useful for passing the address of an external 
function as a parameter to a procedure. When passing a routine 
address as a parameter you should usually pass the address by 
value. For example, VAX/VMS system services expect to receive AST 
procedure entry masks by reference; therefore, the address of the entry 
mask should be in the argument list on the stack. 
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Example 


DECLARE INTEGER A, B 
A = 12 

B = LOC(A) 

PRINT B 

Output 


2146799372 
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The LOG function returns the natural logarithm (base e) of a specified 
number. The LOG function is the inverse of the EXP function. 


Format 


real-var = LOG (real-exp) 
Syntax Rules 
None. 
Remarks 


1. Real-exp must be greater than zero. An attempt to find the logarithm 
of zero or a negative number causes VAX BASIC to signal “Illegal 
argument in LOG” (ERR=53). 


2. The LOG function uses the mathematical constant e as a base. VAX 
BASIC approximates e to be 2.718281828459045 (double precision). 


3. The LOG function returns the exponent to which e must be raised to 
equal real-exp. 


4. VAX BASIC expects the argument of the LOG function to be a real 
expression. When the argument is a real expression, VAX BASIC 
returns a value of the same floating-point size. When the argument is 
not a real expression, VAX BASIC converts the argument to the default 
floating-point size and returns a value of the default floating-point 
size. 
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LOG 
Example 


DECLARE SINGLE exponent 
exponent = L0G(98.6) 
PRINT exponent 


Output 
4.59107 
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LOG10 


The LOG10 function returns the common logarithm (base 10) of a speci- 
fied number. 


Format 


real-var = LOG10 (real-exp) 
Syntax Rules 
None. 
Remarks 


1. Real-exp must be larger than zero. An attempt to find the logarithm 
of zero or a negative number causes VAX BASIC to signal “Illegal 
argument in LOG” (ERR=53). 


2. The LOG10 function returns the exponent to which 10 must be raised 
to equal real-exp. 


3. VAX BASIC expects the argument of the LOG10 function to be a 
real expression. When the argument is a real expression, VAX BASIC 
returns a value of the same floating-point size. When the argument is 
not a real expression, VAX BASIC converts the argument to the default 
floating-point size and returns a value of the default floating-point 
size. 


Statements and Functions 4-177 


LOG10 


DECLARE SINGLE exp_base_10 
exp_base_10 = L0G10(250) 
PRINT exp_base_10 


Output 
2.39794 
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The LSET statement assigns left-justified data to a string variable. LSET 
does not change the length of the destination string variable. 


Format 


LSET _ str-var,... 


Syntax Rules 
1. 
2; 
Remarks 
1. 
2, 


= Str-exp 


Str-var is the destination string. Str-exp is the string value assigned to 
str-var. 


Str-var cannot be a DEF function or function name unless the LSET 
statement is inside the multi-line DEF or function that defines the 
function. 


The LSET statement treats all strings as fixed length. LSET neither 
changes the length of the destination string nor creates new storage. 
Rather, it overwrites the current storage of str-var. 


If the destination string is longer than str-exp, LSET left-justifies str- 
exp and pads it with spaces on the right. If smaller, LSET truncates 
characters from the right of str-exp to match the length of str-var. 
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DECLARE STRING alpha 
alpha = "ABCDE" 

LSET alpha = "FGHIJKLMN" 
PRINT alpha 


Output 
FGHIJ 
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The MAG function returns the absolute value of a specified expression. 
The returned value has the same data type as the expression. 


Format 
var = MAG (exp) 


Syntax Rules 
None. 
Remarks 


1. The returned value is always greater than or equal to zero. The 
absolute value of zero is zero. The absolute value of a positive 
number equals that number. The absolute value of a negative number 
equals that number multiplied by -1. 


2. The MAG function is similar to the ABS function in that it returns 
the absolute value of a number. The ABS function, however, takes 
a floating-point argument and returns a floating-point value. The 
MAG function takes an argument of any numeric data type and 
returns a value of the same data type as the argument. DIGITAL 
recommends the use of the MAG function rather than the ABS and 
ABS% functions, because the MAG function returns a value using the 
data type of the argument. 


Statements and Functions 4-181 


MAG 


DECLARE SINGLE A 
A = -34.6 
PRINT MAG(A) 


Output 
34.6 
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The MAGTAPE function permits your program to control unformatted 
magnetic tape files. 


NOTE 


The MAGTAPE function is supported only for compatibility 
with BASIC-PLUS-2. DIGITAL recommends that you do not 
use the MAGTAPE function for new program development. 


Format 


int-var? = MAGTAPE (func-code, int-var, chnl-exp) 
Syntax Rules 


1. Func-code specifies the code for the MAGTAPE function you want 
to perform. VAX BASIC supports only function code 3, rewind tape. 
Table 4—4 explains how to perform other MAGTAPE functions with 
VAX BASIC. 


2. Int-var is an integer parameter for function codes 4, 5, and 6. 
However, because VAX BASIC supports only function code 3, int-var 
is not used and always equals zero. 


3. Chnl-exp is a numeric expression that specifies a channel number 
associated with the magnetic tape file. 
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Table 4—4: MAGTAPE Functionality in VAX BASIC 


Code 
2 


Remarks 


Function 
Write EOF 


Rewind tape 


Skip records 


Backspace 


Set density or set parity 


Get status 


VAX BASIC Action 


Close channel with the CLOSE 
statement 


Use the RESTORE # statement, 
the REWIND clause on an OPEN 
statement, or the MAGTAPE 
function 


Perform GET operations, ignore 
data until reaching desired record 


Rewind tape, perform GET oper- 
ations, ignore data until reaching 
desired record 

Use the DCL commands 
MOUNT/DENSITY and 
MOUNT/FOREIGN or the 
$MOUNT system service 


Use the RMSSTATUS function 


For more information on the MAGTAPE function, see Appendix A in this 


manual. 


Example 


I = MAGTAPE (3%,0%,2%) 
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The MAP statement defines a named area of statically allocated storage 
called a PSECT, declares data fields in the record, and associates them 
with program variables. 


Format 


MAP (map-name) { [ data-type ] map-item },... 


map-item: 


Syntax Rules 


num-unsubs-var 

num-array-name ( [ int-const1 TO | int-const2,... ) 

record-var 

str-unsubs-var [ = int-const ] 

str-array-name ( [ int-const1 TO | int-const2,... ) [ = int-const ] 
FILL [ ( int-const ) ] [ = int-const ] 

FILL% [ ( int-const ) ] 

FILLS / ( int-const ) ] [ = int-const ] 


Map-name is global to the program and image. It cannot appear 
elsewhere in the program unit as a variable name. 


Map-name can be from 1 through 31 characters. The first character 
of the name must be an alphabetic character (A through Z). The 
remaining characters, if present, can be any combination of letters, 
digits (0 through 9), dollar signs ($), periods (.), or underscores (_). 


Data-type can be any VAX BASIC data type keyword or a data type 
defined by a RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2. 


When you specify a data type, all following map-items, including FILL 
items, are of that data type until you specify a new data type. 


If you specify a dollar sign ($) or percent sign (%) suffix character, 
the variable must be a string or integer data type. 
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10. 


If you do not specify a data type, a map-item without a suffix character 
(% or $) takes the current default data type and size. 


Map-item declares the name and format of the data to be stored. 


¢ Num-unsubs-var and num-array-name specify a numeric variable or 
a numeric array. 


¢ Record-var specifies a record instance. 


e Str-unsubs-var and str-array-name specify a fixed-length string 
variable or array. You can specify the number of bytes to be 
reserved for the variable with the =int-const clause. The default 
string length is 16. 


e The FILL, FILL%, and FILL$ keywords allow you to reserve parts 
of the record buffer within or between data elements and to 
define the format of the storage. Int-const specifies the number 
of FILL items to be reserved. The =int-const clause allows you to 
specify the number of bytes to be reserved for string FILL items. 
Table 4-2 describes FILL item format and storage allocation. 


e In the applicable formats of FILL, (int-const) represents a repeat 
count, not an array subscript. FILL (1), for example, represents n 
elements, not n + 1. 


Variable names, array names and FILL items following a data type 

other than STRING cannot end with a dollar sign. Variable names, 
array names and FILL items following a data type other than BYTE, 
WORD, LONG or INTEGER, cannot end with a percent sign. 


Variables and arrays declared in a MAP statement cannot be declared 
elsewhere in the program by any other declarative statements. 


When you declare an array, VAX BASIC allows you to specify both 
lower and upper bounds. Upper bounds are required; lower bounds 
are optional. 


e Int-const2 specifies the upper bounds of the array and, when 
accompanied by int-const1, must be preceded by the keyword TO. 


e Int-const1 must be less than or equal to int-const2. 


e If you do not specify int-const1, VAX BASIC uses zero as the 
default lower bound. 


e Int-const1 and int-const2 can be any combination of negative and 
positive values. 
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VAX BASIC does not execute MAP statements. The MAP statement 
allocates static storage and defines data at compilation time. 


A program can have multiple maps with the same name. The allo- 
cation for each map overlays the others. Thus, data is accessible in 
many ways. The actual size of the data area is the size of the largest 
map. When you link your program, the size of the map area is the 
size of the largest map with that name. 


Map-items with the same name can appear in different MAP state- 
ments with the same map name only if they match exactly in at- 
tributes such as data type, position, and so forth. If the attributes are 
not the same, VAX BASIC signals an error. For example: 


MAP (ABC) LONG A, B 

MAP (ABC) LONG A, C ! This MAP statement is valid 

MAP (ABC) LONG B, A ! This MAP statement produces an error 
MAP (ABC) WORD A, B ! This MAP statement produces an error 


The third MAP statement causes VAX BASIC to signal the error 
“variable <name> not aligned in multiple references in MAP 
<name> ”, while the fourth MAP statement generates the error 
“attributes of overlaid variable <name> don’t match”. 


The MAP statement should precede any reference to variables declared 
in it. 

Storage space for map-items is allocated in order of occurrence in the 
MAP statement. 


A MAP area can be accessed by more than one program module, as 
long as you define the map-name in each module that references the 
MAP. 


A COMMON area and a MAP area with the same name specify the 
same storage area and are not allowed in the same program module. 
However, a COMMON in one module can reference the storage 
declared by a MAP or COMMON in another module. 


Variables in a MAP statement are not initialized by VAX BASIC. 


A map named in an OPEN statement’s MAP clause is associated with 
that file. The file’s records and record fields are defined by that map. 
The size of the map determines the record size for file I/O, unless the 
OPEN statement includes a RECORDSIZE clause. 
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MAP (BUF1) BYTE AGE, STRING emp_name = 20 
SINGLE emp_nun 


MAP (BUF1) BYTE FILL, STRING last_name (11) = 12, 
FILL = 8, SINGLE FILL 
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The MAP DYNAMIC statement names the variables and arrays whose 
size and position in a storage area can change at run time. The MAP 
DYNAMIC statement is used in conjunction with the REMAP statement. 
The REMAP statement defines or redefines the position in the storage area 
of variables named in the MAP DYNAMIC statement. 


Format 


MAP DYNAMIC = (map-dyn-name){[ data-type Jmap-item j.... 
map-dyn-name: { map-name | 
Static-str-var 


num-unsubs-var 

num-array-name ( [ int-const1 TO ] int-const2 ,...) 
map-item: record-var 

str-unsubs-var 

str-array-name ({ [ int-const1 TO ] int-const2 ,...) 


Syntax Rules 


1. Map-dyn-name can either be a map name or a Static string variable. 
e Map-name is the storage area named in a MAP statement. 


e If you specify a map name, then a MAP statement with the same 
name must precede both the MAP DYNAMIC statement and the 
REMAP statement. 


e When you specify a static string variable, the string must be 
declared before you can specify a MAP DYNAMIC statement or a 
REMAP statement. 


¢ Static-str-var must specify a static string variable or a string 
parameter variable. 
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e If you specify a static-str-var, the following restrictions apply: 
— Static-str-var cannot be a string constant. 


— Static-str-var cannot be the same as any previously declared 
map-item in a MAP DYNAMIC statement. 


— Static-str-var cannot be a subscripted variable. 
— Static-str-var cannot be a record component. 


— Static-str-var cannot be a parameter declared in a DEF or DEF* 
function. 


2. Map-item declares the name and data type of the items to be stored in 
the storage area. All variable pointers point to the beginning of the 
storage area until the program executes a REMAP statement. 


e  Num-unsubs-var and num-array-name specify a numeric variable or 
a numeric array. 


¢ Record-var specifies a record instance. 


¢  Str-unsubs-var and str-array-name specify a string variable or 
array. You cannot specify the number of bytes to be reserved for 
the variable in the MAP DYNAMIC statement. All string items 
have a fixed length of zero until the program executes a REMAP 
statement. 


3. When you specify an array name, VAX BASIC allows you to specify 
both lower and upper bounds. The upper bound is required; the lower 
bound is optional. 


e Int-const1 specifies the lower bounds of the array. 


e Int-const2 specifies the upper bounds of the array and, when 
accompanied by int-const1, must be preceded by the keyword TO. 


¢ Int-const1 must be less than or equal to int-const2. 


e If you do not specify int-const1, VAX BASIC uses zero as the 
default lower bound. 


e Int-const1 and int-const2 can be either negative or positive values. 


4. Data-type can be any VAX BASIC data type keyword or a data type 
defined with a RECORD statement. Data type keywords, size, range, 
and precision are listed in Table 1-2 in this manual. 


5. When you specify a data type, all following map-items are of that data 
type until you specify a new data type. 


6. If you do not specify any data type, map-items take the current default 
data type and size. 


7. Map-items must be separated with commas. 
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8. If you specify a dollar sign or percent sign suffix, the variable must be 
a STRING data type or one of the integer data types. 
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Example 


MAP DYNAMIC 


All variables and arrays declared in a MAP DYNAMIC statement 
cannot be declared elsewhere in the program by any other declarative 
statements. 


The MAP DYNAMIC statement does not affect the amount of storage 
allocated to the map buffer declared in a previous MAP statement or 
the storage allocated to a static string. Until your program executes a 
REMAP statement, all variable and array element pointers point to the 
beginning of the MAP buffer or static string. 


VAX BASIC does not execute MAP DYNAMIC statements. The MAP 
DYNAMIC statement names the variables whose size and position in 
the MAP or static string buffer can change and defines their data type. 


Before you can specify a map name in a MAP DYNAMIC statement, 
there must be a MAP statement in the program unit with the same 
map name. Otherwise, VAX BASIC signals the error “Insufficient 
space for MAP DYNAMIC variables in MAP <name> ”. Similarly, 
before you can specify a static string variable in the MAP DYNAMIC 
statement, the string variable must be declared. Otherwise, VAX 
BASIC signals the same error message. 


A static string variable must be either a variable declared in a MAP or 
COMMON statement or a parameter declared in a SUB, FUNCTION, 
or PICTURE. It cannot be a parameter declared in a DEF or DEF* 
function. 


If a static string variable is the same as a map name, VAX BASIC uses 
the map name if the name appears in a MAP DYNAMIC statement. 


The MAP DYNAMIC statement must lexically precede the REMAP 
statement or VAX BASIC signals the error “MAP variable <name> 
referenced before declaration”. 


MAP (MY.BUF) STRING DUMMY = 512 

MAP DYNAMIC (MY.BUF) STRING LAST, FIRST, MIDDLE, & 
BYTE AGE, STRING EMPLOYER, & 
STRING CHARACTERISTICS 
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The MAR function returns the current margin width of a specified channel. 


Format 


int-var = MAR[%] (chnl-exp) 
Syntax Rules 


The file associated with chnl-exp must be open. 


Remarks 
1. If chnl-exp specifies a terminal and you have not set a margin width 
with the MARGIN statement, the MAR function returns a value of 
zero. If you have set a margin width, the MAR function returns that 
number. . 
2. The value returned by the MAR function is a LONG integer. 
Example 


DECLARE INTEGER width 
MARGIN #0, 80 

width = MAR(O) 

PRINT width 


Output 
80 
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The MARGIN statement specifies the margin width for a terminal or for 
records in a terminal-format file. 


Format 


MARGIN [| #chnl-exp, ] int-exp 
Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 

2. Int-exp specifies the margin width. 


Remarks 


1. If you do not specify a channel, VAX BASIC sets the margin on the 
controlling terminal. 


2. The file associated with chnl-exp must be an open terminal-format file 
or terminal. 


3. VAX BASIC signals the error “Illegal operation” (ERR=141) if the file 
associated with chnl-exp is not a terminal-format file. 


4. If chnl-exp does not correspond to a terminal, and if int-exp is 
zero, VAX BASIC sets the right margin to the size specified by the 
RECORDSIZE clause in the OPEN statement, if the clause is present. 
If no RECORDSIZE clause is present, VAX BASIC sets the margin to 
72 (or, in the case of channel 0, to the width of SYS$OUTPUT). 


5. If chnl-exp is not present or if it corresponds to a terminal, and if 
int-exp is zero, VAX BASIC sets the right margin to the size specified 
by the RECORDSIZE clause in the OPEN statement, if the clause is 
present. If no RECORDSIZE clause is present, VAX BASIC sets the 
margin to 72. 
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6. VAX BASIC prints as much of a specified record as the margin setting 
allows on one line before going to a new line. Numeric fields are 
never split across lines. 


7. If you specify a margin larger than the channel’s record size, VAX 
BASIC signals an error. The default record size for a terminal or 
terminal format file is 132. 


8. The MARGIN statement applies to the specified channel only while 
the channel is open. If you close the channel and then reopen it, 
VAX BASIC uses the default margin. 


Example 


OPEN "EMP.DAT" FOR OUTPUT AS #1 
MARGIN #1, 132 
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The MAT statement lets you implicitly create and manipulate one- and 
two-dimensional arrays. You can use the MAT statement to assign values 
to array elements, or to redimension a previously dimensioned array. 
You can also perform matrix arithmetic operations such as multiplication, 
addition, and subtraction, and other matrix operations such as transposing 
and inverting matrices. 


Format 


Numeric Initialization 


CON 
MAT = num-array = | IDN [ ( int-exp7 [, int-exp2 ] ) ] 
ZER 


String Initialization 
MAT. str-array = NULS [ ( int-exp] [, int-exp2 ] ) ] 
Array Arithmetic 


+ 
MAT num-array? = num-array2 - num-array3 
* 
MAT num-array? = num-array2 * num-array3 [ * num-array4 ] ,... 


Scalar Multiplication 
MAT = num-array4 = ( num-exp ) * num-array5 


Inversion and Transposition 


MAT = num-array6 = { Mi } ( num-array7) 
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Syntax Rules 


Remarks 


Int-exp1 and int-exp2 define the upper bounds of the array being 
implicitly created or the new dimensions of an existing array. 


If you are creating an array, int-exp1 and int-exp2 cannot exceed 10. 


If you do not specify bounds, VAX BASIC creates the array and 
dimensions it to (0 TO 10) or (10 TO 10, 0 TO 10). 


If you specify bounds, VAX BASIC creates the array with the specified 
bounds. If the bounds exceed (0 TO 10) or (10 TO 10, 0 TO 10), VAX 
BASIC signals “Redimensioned array” (ERR=105). 


The lower bounds must be zero. 


To perform MAT operations on arrays larger than (10,10), create the 
input and output arrays with the DIM statement. 


When the array exists, the following rules apply: 


e If you specify upper bounds, VAX BASIC redimensions the array 
to the specified size. However, MAT operations cannot increase 
the total number of array elements. 


e All arrays specified with the MAT statement must have lower 
bounds of zero. If you supply a nonzero value, VAX BASIC 
signals either a compile-time or a run-time error. 


e If you do not specify bounds, VAX BASIC does not redimension 
the array. 


e An array passed to a subprogram and redimensioned with a MAT 
statement remains redimensioned when control returns to the 
calling program, with two exceptions: 


— When the array is within a record and is passed by descriptor 
— When the array is passed by reference 


You cannot use the MAT statement on arrays of more than two 
dimensions. 


You cannot use the MAT statement on arrays of data type DECIMAL 
or on arrays named in a RECORD statement. 
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Initialization 


CON sets all elements of num-array to 1, except those in row and 
column zero. 


IDN creates an identity matrix from num-array. The number of 
rows and columns in num-array must be identical. IDN sets all 
elements to zero except those on the diagonal from num-array(1,1) 
to num-array(n,n), which are set to 1. 


ZER sets all array elements to zero, except those in row and 
column zero. 


NULS sets all elements of a string array to the null string, except 
those in row and column zero. 


Array Arithmetic 


The equal sign (=) assigns the results of the specified operation to 
the elements in num-array1. 


If num-array3 is not specified, VAX BASIC assigns the values of 
num-array2’s elements to the corresponding elements of num- 
array1. Num-array1 must have at least as many rows and columns 
as num-array2. 


Use the plus sign (+) to add the elements of two arrays. Num- 
array2 and num-array3 must have identical bounds. 


Use the minus sign (—) to subtract the elements of two arrays. 
Num-array2 and num-array3 must have identical bounds. 


Use the asterisk (*) to perform matrix multiplication on the 
elements of num-array2 and num-array3 and to assign the results 
to num-array1. This operation gives the dot product of num-array2 
and num-array3. All three arrays must be two-dimensional, and 
the number of columns in num-array2 must equal the number of 
rows in num-array3. VAX BASIC redimensions num-array1 to have 
the same number of rows as num-array2 and the same number of 
columns as num-array3. 


With matrix multiplication, you can specify more than two nu- 
meric arrays. However, each array must be two-dimensional. 
Moreover, in each dimension, the lower bound of each array must 
be zero and the upper bound must be 4. You can use the graphics 
transformation functions, which will automatically create arrays 
with these dimensions. See the DRAW statement in Programming 
with VAX BASIC Graphics for more information. 


Scalar Multiplication 


VAX BASIC multiplies each element of num-array5 by num-exp 
and stores the results in the corresponding elements of num-array4. 
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10. 


11. 


Inversion and Transposition 


e TRN transposes num-array7 and assigns the results to num-array6. 
If num-array7 has m rows and n columns, num-array6 will have n 
rows and m columns. Both arrays must be two-dimensional. 


¢ You cannot transpose a matrix to itself: MAT A = TRN(A) is 
invalid. 


e INV inverts num-array7 and assigns the results to num-array6. 
Num-array7 must be a two-dimensional array that can be reduced 
to the identity matrix with elementary row operations. The row 
and column dimensions must be identical. 


You cannot increase the number of array elements or change the 
number of dimensions in an array when you redimension with the 
MAT statement. For example, you can redimension an array with 
dimensions (5,4) to (4,5) or (3,2), but you cannot redimension that 
array to (5,5) or to (10). The total number of array elements includes 
those in row and column zero. 


If an array is named in both a DIM statement and a MAT statement, 
the DIM statement must lexically precede the MAT statement. 


MAT statements do not operate on elements in the zero element (one- 
dimensional arrays) or in the zero row or column (two-dimensional 
arrays). MAT statements use these elements to store results of inter- 
mediate calculations. Therefore, you should not depend on values in 
row and column zero if your program uses MAT statements. 


Example 1 


{Numeric Initialization 


MAT CONVERT = zer(10,10) 


Example 2 


{Initialization 


MAT na_me$ = NUL$(5,5) 
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Example 3 

'Array Arithmetic 

MAT new_int = old_int - rslt_int 
Example 4 


!'Scalar Multiplication 
MAT Z40 = (4.24) * Z 


Example 5 


{Inversion and Transposition 
MAT Q% = INV (Z) 
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The MAT INPUT statement assigns values from a terminal or terminal- 
format file to array elements. 


Format 


MAT INPUT [ #chnl-exp, ] { array [ ( int-exp7 [, int-exp2 ] ) ] },... 
Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 


2. The file associated with chnl-exp must be an open terminal-format file 
or terminal. If chnl-exp is not specified, VAX BASIC takes data from 
the controlling terminal. 


3. Int-exp1 and int-exp2 define the upper bounds of the array being 
implicitly created or the dimensions of an existing array. 


4. If you are creating an array, int-exp1 and int-exp2 cannot exceed 10. 
Remarks 


1. You cannot use the MAT INPUT statement on arrays of more than 
two dimensions. 


2. You cannot use the MAT INPUT statement on arrays of data type 
DECIMAL or on arrays named in a RECORD statement. 


3. All arrays specified with the MAT INPUT statement must have lower 
bounds of zero. 


4. If you do not specify bounds, VAX BASIC creates the array and 
dimensions it to (10,10). 


4-200 Statements and Functions 


10. 


11. 


12: 
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MAT INPUT 


If you do specify upper bounds, VAX BASIC creates the array with the 
specified bounds. If the bounds exceed (10) or (10,10), VAX BASIC 
signals “Redimensioned array” (ERR=105). 

To use the MAT INPUT statement with arrays larger than (10,10), 
create the input and output arrays with the DIM statement. 


When the array exists, the following rules apply: 


e If you specify bounds, VAX BASIC redimensions the array to the 
specified size. However, MAT INPUT cannot increase the total 
number of array elements. 


e If you do not specify bounds, VAX BASIC does not redimension 
the array. 

The MAT INPUT statement prompts with a question mark on termi- 

nals open on channel #0 only unless a SET NO PROMPT statement 

has been executed. See the description of the SET PROMPT statement 

for more information. 

Use commas to separate data elements and a line terminator to end 

the input of data. Use an ampersand (&) before the line terminator to 

continue data over more than one line. 

The MAT INPUT statement assigns values by row. For example, it 

assigns values to all elements in row 1 before beginning row 2. 

The MAT INPUT statement assigns the row number of the last data 

element transferred into the array to the system variable NUM. 

The MAT INPUT statement assigns the column number of the last 

data element transferred into the array to the system variable NUM2. 

If there are fewer elements in the input data than there are array 

elements, VAX BASIC does not change the remaining array elements. 


If there are more data elements in the input stream than there are 
array elements, VAX BASIC ignores the excess. 


Row zero and column zero are not changed. 


For information about graphics input, see the MAT LOCATE and the 
MAT GET statements in Programming with VAX BASIC Graphics. 
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MAT INPUT XYZ(5,5) 
MAT PRINT XYZ; 


Output 


?7°1,2,3,4,5 


oooor 
oOOOnN 
ooo 0 Ww 
oooorF 
oooon 
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The MAT LINPUT statement receives string data from a terminal or 
terminal-format file and assigns it to string array elements. 


Format 
MAT LINPUT 


Syntax Rules 


Remarks 


[ #chnl-exp, ] { str-array [ ( int-exp? [, int-exp2 ] ) ] },... 


Chnl-exp is a numeric expression that specifies a channel number 
associated with a file or terminal. It must be immediately preceded by 
a number sign (#). 

The file associated with chnl-exp must be an open terminal-format file 
or terminal. If a channel is not specified, VAX BASIC takes data from 
the controlling terminal. 

Int-exp1 and int-exp2 define the upper bounds of the array being 
implicitly created or the dimensions of an existing array. 


If you are creating an array, int-exp1 and int-exp2 cannot exceed 10. 


You cannot use the MAT LINPUT statement on arrays of more than 
two dimensions. 


You cannot use the MAT LINPUT statement on arrays of data type 
other than STRING or on arrays named in a RECORD statement. 


If you do not specify bounds, VAX BASIC creates the array and 
dimensions it to (10,10). 


If you do specify upper bounds, VAX BASIC creates the array with the 
specified bounds. If the bounds exceed (10) or (10,10), VAX BASIC 
signals “Redimensioned array” (ERR=105). 
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5. All arrays specified with the MAT LINPUT statement must have lower 
bounds of zero. 


6. To use MAT LINPUT with arrays larger than (10,10), create the input 
and output arrays with the DIM statement. 


7. When the array exists, the following rules apply: 


e If you specify bounds, VAX BASIC redimensions the array to the 
specified size. However, MAT LINPUT cannot increase the total 
number of array elements. 


e If you do not specify bounds, VAX BASIC does not redimension 
the array. 


8. For terminals open on channel zero only, the MAT LINPUT statement 
prompts with a question mark (unless a SET NO PROMPT statement 
has been executed) for each string array element, starting with element 
(1,1). VAX BASIC assigns values to all elements of row 1 before 
beginning row 2. 

9. The MAT LINPUT statement assigns the row number of the last data 
element transferred into the array to the system variable NUM. 


10. The MAT LINPUT statement assigns the column number of the last 
data element transferred into the array to the system variable NUM2. 


11. Typing only a line terminator in response to the question mark prompt 
causes VAX BASIC to assign a null string to that string array element. 


12. MAT LINPUT does not change row and column zero. 
Example 


DIM cus_rec$(3,3) 
MAT LINPUT cus_rec$(2,2) 
PRINT cus_rec$(1i,1) 
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PRINT cus_rec$(1,2) 
PRINT cus_rec$(2,1) 
PRINT cus_rec$(2,2) 


Output 


? Babcock 
? Santani 
? Lloyd 

? Kelly 
Babcock 
Santani 
Lloyd 
Kelly 


MAT LINPUT 
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MAT PRINT 


The MAT PRINT statement prints the contents of a one- or two- 
dimensional array on your terminal or assigns the value of each array 
element to a record in a terminal-format file. 


Format 


MAT PRINT [#chnl-exp, ] { array [ ( int-exp1 [, int-exp2 ]) 1 has 


a 
s 
Uy 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file or terminal. It must be immediately preceded by 
a number sign (#). 


2. The file associated with chnl-exp must be an open terminal-format file 
or terminal. If you do not specify a channel, VAX BASIC takes data 
from the controlling terminal. 


3. Int-exp1 and int-exp2 define the upper bounds of the array being 
implicitly created or the dimensions of an existing array. 


4. The separator (comma or semicolon) determines the output format for 
the array: 


e If you use a comma, VAX BASIC prints each array element in a 
new print zone and starts each row on a new line. 


e If you use a semicolon, VAX BASIC separates each array element 
with a space and starts each row on a new line. 


e If you do not use a separator character, VAX BASIC prints each 
array element on its own line. 
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Remarks 


MAT PRINT 


You cannot use the MAT PRINT statement on arrays of more than 
two dimensions. 


You cannot use the MAT PRINT statement on arrays of data type 
DECIMAL or on arrays named in a RECORD statement. 


When you use the MAT PRINT statement to print more than one 
array, each array name except the last must be followed with either 
a comma or a semicolon. VAX BASIC prints a blank line between 
arrays. 


If the array does not exist, the following rules apply: 

All arrays specified with the MAT PRINT statement must have lower 

bounds of zero. 

e If you do not specify bounds, VAX BASIC creates the array and 
dimensions it to (10,10). 


e If you specify upper bounds, VAX BASIC creates the array with 
the specified bounds. If the bounds exceed (10) or (10,10), VAX 
BASIC prints the elements (10) or (10,10), and signals “Subscript 
out of range” (ERR=55). 


When the array exists, the following rules apply: 


e If the specified bounds are smaller than the maximum bounds of 
a dimensioned array, VAX BASIC prints a subset of the array, but 
does not redimension the array. For example, if you use the DIM 
statement to dimension A(20,20), and then MAT PRINT A(2,2), 
VAX BASIC prints elements (1,1), (1,2), (2,1), and (2,2) only; 
array A(20,20) does not change. 

e If you do not specify bounds, VAX BASIC prints the entire array. 


The MAT PRINT statement does not print elements in row or column 
zero. 


The MAT PRINT statement cannot redimension an array. 
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MAT PRINT 


DIM cus_rec$(3,3) 
MAT LINPUT cus_rec$(2,2) 
MAT PRINT cus_rec$(2,2) 


Output 


? Babcock 
? Santani 
? Lloyd 

? Kelly 
Babcock 
Santani 
Lloyd 
Kelly 
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MAT READ 


MAT READ 


The MAT READ statement assigns values from DATA statements to array 
elements. 


Format 


MAT READ { array [ ( int-exp7 [, int-exp2 ] ) ] },... 


Syntax Rules 


Remarks 


Int-exp1 and int-exp2 define the upper bounds of the array being 
implicitly created or the dimensions of an existing array. 


If you are creating an array, int-exp1 and int-exp2 cannot exceed 10. 


If you do not specify bounds, VAX BASIC creates the array and 
dimensions it to (10) or (10,10). 


If you specify bounds, VAX BASIC creates the array with the specified 
bounds. If the bounds exceed (10) or (10,10), VAX BASIC signals 
“Redimensioned array” (ERR=105). 

To read arrays larger than (10,10), create the array with the DIM 
statement. 

All arrays specified with the MAT statement must have lower bounds 
of zero. 

When the array exists, the following rules apply: 


e If you specify upper bounds, VAX BASIC redimensions the array 
to the specified size. However, MAT READ cannot increase the 
total number of array elements. 


e If you do not specify bounds, VAX BASIC does not redimension 
the array. 


Statements and Functions 4-209 


MAT READ 


10. 


11. 


12, 


13. 


All the DATA statements must be in the same program unit as the 
MAT READ statement. 


The MAT READ statement assigns data items by row. For example, it 
assigns data items to all elements in row 1 before beginning row 2. 
The MAT READ statement does not read elements into row or column 
zero. 

The MAT READ statement assigns the row number of the last data 
element transferred into the array to the system variable, NUM. 

The MAT READ statement assigns the column number of the last data 
element transferred into the array to the system variable, NUM2. 

If you use MAT READ for an existing array without specifying bounds, 
VAX BASIC does not redimension the array. If you use MAT READ 
for an existing array and specify bounds, VAX BASIC redimensions 
the array. 

You cannot use the MAT READ statement on arrays of more than two 
dimensions. 


You cannot use the MAT READ statement on arrays of data type 
DECIMAL or on arrays named in a RECORD statement. 


MAT READ A(3,3) 
MAT READ B(3,3) 
PRINT 

PRINT "Matrix A" 
PRINT 

MAT PRINT A; 
PRINT 

PRINT "Matrix B" 
PRINT 

MAT PRINT B; 
DATA 1,2,3,4,5,6 
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MAT READ 


Output 
Matrix A 


1 2 
4 5 
0 0 


Matrix 


0 0 
0 O 
0 0 


oo 0 WB Ow 
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MAX 





MAX 


The MAX function compares the values of two or more numeric expres- 
sions and returns the highest value. 


Format 


num-var = MAX ( num-exp1, num-exp2 [ , num-exp3 ,...]) 
Syntax Rules 


VAX BASIC allows you to specify up to eight numeric expressions. 


Remarks 
1. If you specify values with different data types, VAX BASIC performs 
data type conversions to maintain precision. 
2. VAX BASIC returns a function result whose data type is compatible 
with the values you supply. 
Example 


DECLARE REAL John_grade, & 
Bob_grade, & 
Joe_grade, & 
highest _grade 
INPUT "John's grade"; John_grade 
INPUT "Bob's grade"; Bob_grade 
INPUT "Joe's grade"; Joe_grade 
highest_grade = MAX(John_grade, Bob_grade, Joe_grade) 
PRINT "The highest grade is"; highest_grade 
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MAX 


Output 


John's grade? 90 
Bob's grade? 95 
Joe's grade? 79 
The highest grade is 95 
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MIDS 


MIDS 


MID$ can be used either as a statement or as a function. The MID$ 
statement performs substring insertion into a string. The MID$ function 
extracts a specified substring from a string expression. 


Format 


MID$ statement 
MID[$]  ( str-var, int-exp1 [ , int-exp2 ] ) = str-exp 


MID$ function 
str-var = MID[$] (str-exp, int-exp1, int-exp2) 


Syntax Rules 


1. Int-exp1 specifies the position of the substring’s first character. 
Int-exp2 specifies the length of the substring. 


Remarks 


1. If int-exp1 is less than 1, VAX BASIC assumes a starting character 
position of 1. 


2. If int-exp2 is less than or equal to zero, VAX BASIC assumes a length 
of zero. 


3. If you specify a floating-point expression for int-exp1 or int-exp2, VAX 
BASIC truncates it to a LONG integer. 


4. MID$§ statement 


e The MID$ statement replaces a specified portion of str-var with 
str-exp. 


e If int-exp1 is greater than the length of str-var, str-var remains 
unchanged. 
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Examples 


MIDS 


The length of str-var does not change regardless of the value of 
int-exp2. 

If the optional int-exp2 is not specified, VAX BASIC assumes int- 
exp2 to be the length of str-exp minimized by the length of str-var 
minus int-exp1. For example: 


A$ = "ABCDEFG" 

MID$ (A$,3) = "123456789" 
PRINT A$ 

Output 


"AB12345" 


If int-exp2 is less than or equal to zero, str-var remains unchanged. 


If int-exp2 is greater than the length of str-var, VAX BASIC 
assumes int-exp2 to be equal to the length of sétr-var. 


Int-exp2 is always minimized against the length of str-var minus 
int-exp1. 


5. MID$ function 


The MID§$ function extracts a substring from str-exp and stores it 
in str-var. 


If int-exp1 is greater than the length of str-exp, MID$ returns a 
null string. 


If int-exp2 is greater than the length of str-exp, VAX BASIC returns 
the string that begins at int-exp1 and includes all characters 
remaining in str-exp. 


If int-exp2 is less than or equal to zero, MID$ returns a null string. 


Example 1 


!MID$ Function 

DECLARE STRING old_string, new_string 
old_string = "ABCD" 

new_string = MID$(old_string,1,3) 
PRINT new_string 


Output 1 


ABC 
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MIDS 


Example 2 


!MID$ Statement 

DECLARE STRING old_string, replace_string 
old_string = "ABCD" 

replace_string = "123" 

PRINT old_string 

MID$(old_string,1,3) = replace_string 
PRINT old_string 


Output 2 


ABCD 
123D 
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The MIN function compares the values of two or more numeric expres- 
sions and returns the smallest value. 


Format 


num-var = MIN ( num-exp1, num-exp2 [ , num-exp3 ,... J) 
Syntax Rules 


VAX BASIC allows you to specify up to eight numeric expressions. 


Remarks 
1. If you specify values with different data types, VAX BASIC performs 
data type conversions to maintain precision. 
2. VAX BASIC returns a function result whose data type is compatible 
with the values you supply. 
Example 


DECLARE REAL John_grade, & 
Bob_grade, & 
Joe_grade, & 
lowest _grade 
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INPUT "John's grade"; John_grade 

INPUT "Bob's grade"; Bob_grade 

INPUT "Joe's grade"; Joe_grade 

lowest_grade = MIN(John_grade, Bob_grade, Joe_grade) 
PRINT “The lowest grade is"; lowest_grade 


Output 


John's grade? 95 
Bob's grade? 100 
Joe's grade? 84 
The lowest grade is 84 
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The MOD function divides a numeric value by another numeric value and 
returns the remainder. 


Format 


num-var = MOD ( num-exp1, num-exp2 ) 
Syntax Rules 
Num-exp1 is divided by num-exp2. 
Remarks 


1. If you specify values with different data types, VAX BASIC performs 
data type conversions to maintain precision. 


2. VAX BASIC returns a function result whose data type is compatible 
with the values you supply. 


3. The function result is either a positive or negative value, depending 
on the value of the first numeric expression. For example, if the first 
numeric expression is negative, then the function result will also be 
negative. 
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Example 


DECLARE REAL A,B 

A = 500 

B = MOD(A,70) 

PRINT "The remainder equals";B 


Output 


The remainder equals 10 
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MOVE 


MOVE 


The MOVE statement transfers data between a record buffer and a list of 
variables. 


Format 


MOVE bs om } #chni-exp, move-item,... 


num-var 
num-array { [,]...) 
str-var [ = int-exp ] 
move-item: str-array ( [,]...) [ = int-exp ] 
[ data-type ] FILL [ ( int-exp ) ] [ = int-const ] 
FILL% [ ( int-exp ) ] 
FILLS [ ( int-exp ) ] [ = int-exp ] 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 

2. Move-item specifies the variable or array to which or from which data 
is to be moved. 


3. Parentheses indicate the number of dimensions in a numeric array. 
The number of dimensions is equal to the number of commas plus 
1. Empty parentheses indicate a one-dimensional array, one comma 
indicates a two-dimensional array, and so on. 
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MOVE 


4. Str-var and str-array specify a fixed length string variable or array. 
‘Parentheses indicate the number of dimensions in a string array. The 
number of dimensions is equal to the number of commas plus 1. You 
can specify the number of bytes to be reserved for the variable or 
array elements with the =int-exp clause. The default string length for a 
MOVE FROM statement is 16. For a MOVE TO statement, the default 
is the string’s length. 


5. The FILL, FILL%, and FILL$ keywords allow you to transfer fill 
items of a specific data type. Table 4-2 shows FILL item formats, 
representations, and storage requirements. 


e If you specify a data type before the FILL keyword, the fill is of 
that data type. If you do not specify a data type, the fill is of the 
default data type. Data-type can be any VAX BASIC data type 
keyword or a data type defined by a RECORD statement. Data 
type keywords, size, range, and precision are listed in Table 1-2 
in this manual. 


e FILL items following a data type other than STRING cannot end 
with a dollar sign. FILL items following a data type other than 
BYTE, WORD, LONG or INTEGER, cannot end with a percent 
sign. 

e Int-exp specifies the number of FILL items to be moved. 


e FILL% indicates integer fill. FILL$ indicates string fill. The =int- 
exp clause specifies the number of bytes to be moved for string 
FILL items. 


e In the applicable formats of FILL, (int-exp) represents a repeat 
count, not an array subscript. FILL (n), for example, represents n 
elements, not 1 + 1. 


6. You cannot use an expression or function reference as a move-item. 


Remarks 


1. Before a MOVE FROM statement can execute, the file associated with 
chnl-exp must be open and there must be a record in the record buffer. 


2. A MOVE statement neither transfers data to or from external devices, 
nor invokes the VAX Record Management Services (RMS). Instead, 
it transfers data between user areas. Thus, a record should first be 
fetched with the GET statement before you use a MOVE FROM 
statement, and a MOVE TO statement should be followed by a PUT 
or UPDATE statement that writes the record to a file. 
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MOVE 


3. MOVE FROM transfers data from the record buffer to the move-item. 
4. MOVE TO transfers data from the move-item to the record buffer. 


5. The MOVE statement does not affect the record buffer’s size. If 
a MOVE statement partially fills a buffer, the rest of the buffer is 
unchanged. If there is more data in the variable list than in the buffer, 
VAX BASIC signals “MOVE overflows buffer” (ERR=161). 


6. Each MOVE statement to or from a channel transfers data starting at 
the beginning of the buffer. For example: 


MOVE FROM #1%, I%, A$ = I% 


In this example, VAX BASIC assigns the first value in the record buffer 
to 1%; the value of 1% is then used to determine the length of A$. 


7. If a MOVE statement operates on an entire array, the following 
conditions apply: 
e VAX BASIC transfers elements of row and column zero (in con- 
trast to the MAT statements). 


e The storage size of the array elements and the size of the array 
determine the amount of data moved. A MOVE statement that 
transfers data from the buffer to a longword integer array transfers 
the first four bytes of data into the first element (for example, 
(0,0)), the next four bytes of data into element (0,1), and so on. 


8. If the MOVE TO statement specifies an explicit string length, the 
following restrictions apply: 


e If the string is equal to or longer than the explicit string length, 
VAX BASIC moves only the specified number of characters into 
the buffer. 


e If the string is shorter than the explicit string length, VAX BASIC 
moves the entire string and pads it with spaces to the specified 
length. 


9. VAX BASIC does not check the validity of data during the MOVE 
operation. 


MOVE FROM #4%,, RUNSY,, HITSY, ERRORS’, RBI%, BAT_AVERAGE 
MOVE TO #9%, FILL$ = 10%, A$ = 10%, B$ = 30%, C$ = 2% 
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NAME...AS 


The NAME...AS statement renames the specified file. 


Format 
NAME _file-spec! AS file-spec2 


Syntax Rules 


File-spec1 and file-spec2 must be string expressions. 


2. There is no default file type in file-specl or file-spec2. If the file to be 
renamed has a file type, file-spec1 must include both the file name and 
the file type. 


3. If you specify only a file name, VAX BASIC searches for a file with no 
file type. If you do not specify a file type for file-spec2, VAX BASIC 
names the file, but does not assign a file type. 


4. You can include a directory name but not a device name. If you 
specify a directory name with file-spec2, the file will be placed in the 
specified directory. If you do not specify a directory name the default 
is the current directory. 

5. File version numbers are optional. VAX BASIC renames the highest 
version of file-spec1 if you do not specify a version number. 


Remarks 


1. If the file specified by file-spec1 does not exist, VAX BASIC signals 
“Can't find file or account” (ERR=5). 


2. If you use the NAME...AS statement on an open file, VAX BASIC does 
not rename the file until it is closed. 


3. You cannot use the NAME...AS statement to move a file between 
devices. You can only change the directory, name, type, or version 
number. 
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*xample 


$ Directory USERS$$DISK : [BASIC_PROG) 
Directory USER$$DISK: [BASIC_PROG] 
FIRST_PROG.BAS; 1 


Total of 1 file. 
$ BASIC 


VAX BASIC V3.0 


Ready 


NAME "FIRST_PROG.BAS" AS "SECOND_PROG.BAS" 
Ready 


EXIT 

$ Directory USER$$DISK: [BASIC_PROG] 
Directory USER$$DISK: [BASIC_PROG] 
SECOND_PROG.BAS; 1 

Total of i file. 


NAME...AS 


Statements and Functions 


4-225 


NEXT 


NEXT 


Format 


The NEXT statement marks the end of a FOR, UNTIL, or WHILE loop. 


NEXT /[ num-unsubs-var ] 


Syntax Rules 


Remarks 


1. Num-unsubs-var is required in a FOR...NEXT loop and must corre- 
spond to the num-unsubs-var specified in the FOR statement. 


2. Num-unsubs-var is not allowed in an UNTIL or WHILE loop. 
3. Num-unsubs-var must be a numeric, unsubscripted variable. 


Each NEXT statement must have a corresponding FOR, UNTIL, or WHILE 
statement or VAX BASIC signals an error. 


PROGRAM calculating_pay 
DECLARE INTEGER no_hours, & 
SINGLE weekly_pay, minimum_wage 
Minimum_wage = 3.65 
no_hours = 40 
WHILE no_hours > 0 


INPUT "Enter the number of hours you intend to work this week";no_hours 


weekly_pay = no_hours * minimum_wage 


PRINT "If you worked";no_hours;"hours, your pay would be"; weekly_pay 


NEXT 
END PROGRAM 
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NEXT 


Output 


Enter the number of hours you intend to work this week? 35 
If you worked 35 hours, your pay would be 127.75 

Enter the number of hours you intend to work this week? 23 
If you worked 23 hours, your pay would be 83.95 

Enter the number of hours you intend to work this week? 0 

If you worked O hours your pay would be 0 
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NOECHO 


The NOECHO function disables echoing of input on a terminal. 


Format 
int-var = NOECHO (chni-exp) 


Syntax Rules 


Chnl-exp must specify a terminal. 


Remarks 
1. If you specify NOECHO, VAX BASIC accepts characters typed on the 
terminal as input, but the characters do not echo on the terminal. 
2. The NOECHO function is the complement of the ECHO function; 
NOECHO disables the effect of ECHO and vice versa. 
3. NOECHO always returns a value of zero. 
Example 


DECLARE INTEGER Y, & 
STRING pass_word 
Y = NOECHO(O) 
INPUT "Enter your password"; pass_word 
IF pass_word = "DARLENE" THEN PRINT "Confirmed" 
Y = ECHO(O) 


Output 


Enter your password? 
Confirmed 
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NOMARGIN 


NOMARGIN 


The NOMARGIN statement removes the right margin limit set with the 
MARGIN statement for a terminal or a terminal-format file. 


Format 
NOMARGIN § [| #chni-exp ] 


Syntax Rules 


Chnl-exp is a numeric expression that specifies a channel number asso- 
ciated with a file. It must be immediately preceded by a number sign 


(#). 
Remarks 


1. When you specify NOMARGIN, the right margin is set to 132. 


2. Chnl-exp, if specified, must be an open terminal-format file or a 
terminal. 


3. If you do not specify a channel, VAX BASIC sets the margin on the 
controlling terminal to 132. 


4. The NOMARGIN statement applies to the specified channel only 
while the channel is open. If you close the channel and then reopen 
it, VAX BASIC uses the default margin of 72. 
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NOMARGIN 


OPEN "EMP.DAT" FOR OUTPUT AS #1 
NOMARGIN #1 
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The NUM function returns the row number of the last data element 
transferred into an array by a MAT I/O statement. 


Format 
int-var = NUM 


Syntax Rules 
None. 
Remarks 


1. NUM returns a value of zero if it is invoked before VAX BASIC has 
executed any MAT I/O statements. 


2. For a two-dimensional array, NUM returns an integer specifying the 
row number of the last data element transferred into the array. For a 
one-dimensional array, NUM returns the number of elements entered. 


3. The value returned by the NUM function is an integer of the default 
size. 
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Example 


OPEN "STU_ACCT" FOR INPUT AS #2 
DIM stu_rec$(3,3) 

MAT INPUT #2, stu_rec$ 

PRINT "Row count =";NUM 

PRINT "Column number =";NUM2 


Output 


Row count = 1 
Column number = 1 
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NUM2 


NUM2 


The NUM2 function returns the column number of the last data element 
transferred into an array by a MAT I/O statement. 


Format 
int-var = NUM2 


Syntax Rules 
None. 
Remarks 


1. NUM2 returns a value of zero if it is invoked before VAX BASIC 
has executed any MAT I/O statements or if the last array element 
transferred was in a one-dimensional list. 


2. The NUM2 function returns an integer specifying the column number 
of the last data element transferred into an array. 


3. The value returned by the NUM2 function is an integer of the default 
size. 
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NUM2 


Example 


OPEN "STU_ACCT" FOR INPUT AS #2 
DIM stu_rec$(3,3) 

MAT INPUT #2, stu_rec$ 

PRINT "Row count =";NUM 

PRINT "Column number =";NUM2 


Output 


Row count = i 
Column number = 1 
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NUMS 


The NUM$ function evaluates a numeric expression and returns a string 
of characters in PRINT statement format, with leading and trailing spaces. 


Format 


str-var = NUM$ (num-exp) 
Syntax Rules 
None. 
Remarks 


1. If num-exp is positive, the first character in the string expression is a 
space. If num-exp is negative, the first character is a minus sign (—). 


2. The NUM6$ function does not include trailing zeros in the returned 
string. If all digits to the right of the decimal point are zeros, NUM$ 
omits the decimal point as well. 

3. When num-exp is a floating-point variable and has an integer portion 
of six decimal digits or less (for example, 1234.567), VAX BASIC 
rounds the number to six digits (1234.57). If num-exp has seven 
decimal digits or more, VAX BASIC rounds the number to six digits 
and prints it in E format. 


4. When num-exp is between 0.1 and 1 and contains more than six digits, 
VAX BASIC rounds it to six digits. When num-exp is smaller than 0.1, 
VAX BASIC rounds it to six digits and prints it in E format. 


5. If num-exp is a longword integer, the returned string can have up to 
10 digits. 


6. If num-exp is a DECIMAL value, the returned string can have up to 31 
digits. 
7. The last character in the returned string is a space. 
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Example 


DECLARE STRING number 
number = NUM$(34.5500/31.8) 
PRINT number 


Output 
1.08648 
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NUM1$ 


The NUM1$§ function changes a numeric expression to a numeric character 
string without leading and trailing spaces and without rounding. 


Format 


str-var = NUM1$ (num-exp) 
Syntax Rules 
None. 
Remarks 


1, The NUM1$ function returns a string consisting of numeric characters 
and a decimal point that corresponds to the value of num-exp. Leading 
and trailing spaces are not included in the returned string. 


2. The NUM1§ function returns a maximum of 
e 3 digits for BYTE integers 
e 5 digits for SINGLE floating-point numbers and WORD integers 
e 10 digits for LONG integers 
¢ 16 digits for DOUBLE floating-point numbers 
e 15 digits for GFLOAT floating-point numbers 
e 33 digits for HFLOAT floating-point numbers 
e 31 digits for DECIMAL numbers 
3. The NUM1§$ function does not produce E notation. 
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NUM1$S 


DECLARE STRING number 
number = NUM1$(PI/2) 
PRINT number 


Output 
1.5708 
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ON ERROR GO BACK 


ON ERROR GO BACK 


Under certain conditions, an ON ERROR GO BACK statement executed in 
a subprogram or DEF function transfers control to the calling program. 


NOTE 


The ON ERROR GO BACK statement is supported for com- 
patibility with other DIGITAL BASICs. For new program 
development, DIGITAL recommends that you use WHEN 
blocks. 


Format 


an ERAOT Bonet 


Syntax Rules 


The ON ERROR GO BACK statement is illegal inside a protected region 
or within an attached or detached handler. Use the EXIT HANDLER 
statement instead. 


Remarks 


1. If there is no error outstanding, execution of an ON ERROR GO BACK 
statement causes subsequent errors to return control to the calling 
program’s error handler. 


2. If there is an error outstanding, execution of am ON ERROR GO BACK 
statement immediately transfers control to the calling program’s error 
handler. 


3. By default, DEF functions and subprograms re-signal errors to the 
calling program. 
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ON ERROR GO BACK 


The ON ERROR GO BACK statement remains in effect until the 
program unit completes execution, until VAX BASIC executes another 
ON ERROR statement, or until VAX BASIC enters a protected region. 


An ON ERROR GO BACK statement executed in the main program is 
equivalent to an ON ERROR GOTO 0 statement. 


If a main program calls a subprogram named SUB1, and SUB1 calls 
the subprogram named SUB2, an ON ERROR GO BACK statement 
executed in SUB2 transfers control to SUB1’s error handler when an 
error occurs in SUB2. If SUB1 also has executed an ON ERROR GO 
BACK statement, VAX BASIC transfers control to the main program's 
error handling routine. 


For current program development, see the WHEN ERROR statement. 


DIGITAL does not recommend that you mix ON ERROR state- 
ments with protected regions in the same program unit. For more 
information, see the VAX BASIC User Manual. 


IF ERR = 11 


THEN 

RESUME err_hand 
ELSE 

ON ERROR GO BACK 


END IF 
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ON ERROR GOTO 


ON ERROR GOTO 


The ON ERROR GOTO statement transfers program control to a specified 
line or label in the current program unit when an error occurs under 
certain conditions. 


NOTE 


The ON ERROR GOTO statement is supported for compatibility 
with other DIGITAL BASICs. For new program development, 
DIGITAL recommends that you use WHEN blocks. 


Format 


‘ ONERROR , GO TO 


t t 
ON ERROR Soe | oo 


Syntax Rules 


1. You cannot specify an ON ERROR GOTO statement within a pro- 
tected region or handler. 


2. Target must be a valid VAX BASIC line number or label and must exist 
in the same program unit as the ON ERROR GOTO statement. 


3. If an ON ERROR GOTO statement is in a DEF function, target must 
also be in that function definition. 
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Remarks 


VAX BASIC transfers program control to a specified line number or 
label under two conditions: 


e If an error does not occur within the protected region of WHEN 
block. 


e If an error occurs within the protected region of a WHEN block 
and was propagated by the handler associated with the WHEN 
block. 

Execution of an ON ERROR GOTO statement causes subsequent 

errors to transfer control to the specified target. 

The ON ERROR GOTO statement remains in effect until the program 

unit completes execution or until VAX BASIC executes another ON 

ERROR statement. 

VAX BASIC does not allow recursive error handling. If a second error 

occurs during execution of an error-handling routine, control passes to 

the VAX BASIC error handler and the program stops executing. 

For current program development, see the WHEN ERROR statement. 


DIGITAL does not recommend that you mix ON ERROR statements 
with protected regions within the same program unit. For more 
information, see the VAX BASIC User Manual. 


SUB LIST (STRING A) 
DECLARE STRING B 
ON ERROR GOTO err_block 
OPEN A FOR INPUT AS FILE #1 
Input_loop: 

LINPUT #1, B 
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PRINT B 


GOTO Input_loop 


err_block: 
IF (ERR=11%) 
THEN 
CLOSE #1% 
RESUME done 
ELSE 
ON ERROR GOTO 0 
END IF 
done: 
END SUB 


ON ERROR GOTO 
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ON ERROR GOTO 0 


The ON ERROR GOTO 0 statement disables ON ERROR error handling 
and passes control to the VAX BASIC error handler when an error occurs. 


NOTE 


The ON ERROR GOTO 0 statement is supported for com- 
patibility with other DIGITAL BASICs. For new program 

development, DIGITAL recommends that you use WHEN 
blocks. 


Format 


Lonennon J \ coro. | ° 


Syntax Rules 


VAX BASIC does not allow you to specify an ON ERROR GOTO 0 
statement within an attached or detached handler or within a protected 
region. 


Remarks 


1. If an error is outstanding, execution of an ON ERROR GOTO 0 
statement immediately transfers control to the VAX BASIC error 
handler. The VAX BASIC error handler will report the error and exit 
the program. 


2. If there is no error outstanding, execution of an ON ERROR GOTO 
0 statement causes subsequent errors to transfer control to the VAX 
BASIC error handler. 


4-244 Statements and Functions 


ON ERROR GOTO 0 


3. When an ON ERROR GOTO 0 statement is executed, control is 
transferred to the VAX BASIC error handler if an error did not occur 
within the protected region of a WHEN block. 


4. If an error occurs within the protected region of a WHEN block and 
was propagated by the handler associated with the WHEN block, VAX 
BASIC transfers control to the specified line number or label contained 
in the subprogram or DEF. 


5. For current program development, see the WHEN ERROR statement. 


6. DIGITAL does not recommend that you mix ON ERROR statements 
with attached or detached handlers within the same program unit. For 
more information, see the VAX BASIC User Manual. 


ON ERROR GOTO err_routine 

FOR I = 1% TO 10% 
PRINT "Please type a number" 
INPUT A 

NEXT I 

err_routine: 

IF ERR = 50 


ON ERROR GOTO 0 
END IF 


Output 


Please type a number 
? (CTRL/Z| 
“%BAS-F-ILLUSADEV, Illegal usage for device 
-BAS-I-ON_CHAFIL, on channel O for file SYS$INPUT: [TUTTI]SYSINPUT .DAT; 

at user PC 00000632 
-RMS-F-DEV, error in device name or inappropriate device type for operation 
-BAS-I-FROLINMOD, from line 10 in module BADUSER 
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ON...GOSUB 


The ON...GOSUB statement transfers program control to one of several 
subroutines, depending on the value of a control expression. 


Format 


ON = int-exp GOSUB target ,... [OTHERWISE target ] 
Syntax Rules 


1. Int-exp determines which target VAX BASIC selects as the GOSUB 
argument. If int-exp equals 1, VAX BASIC selects the first target. If 
int-exp equals 2, VAX BASIC selects the second target, and so on. 


2. Target must be a valid VAX BASIC line number or label and must exist 
in the current program unit. 


Remarks 


1. Control cannot be transferred into a statement block (such as 
FOR...NEXT, UNTIL...NEXT, WHILE...NEXT, DEF...END DEF, 
SELECT...END SELECT, WHEN...END WHEN, or HANDLER...END 
HANDLER). 


2. If there is an OTHERWISE clause, and if int-exp is less than 1 or 
greater than the number of targets in the list, VAX BASIC selects the 
target of the OTHERWISE clause. 


3. If there is no OTHERWISE clause, and if int-exp is less than 1 or 
greater than the number of targets in the list, VAX BASIC signals “ON 
statement out of range” (ERR=58). 


4. Ifa target specifies a nonexecutable statement, VAX BASIC transfers 
control to the first executable statement that lexically follows the 
target. 


5. You can only use the ON...GOSUB statement inside a handler if all 
the targets are contained within the handler. 
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Example 


100 


1000 
2000 


3000 


July 


ON...GOSUB 


If you fail to handle an exception that occurs while an ON...GOSUB 
statement in the body of a subroutine is executing, the exception is 
handled by the default error handler. The exception is not handled 
by any WHEN block surrounding the ON...GOSUB statement that 
invoked the subroutine. 


You can specify the ON...GOSUB statement inside a WHEN block 
if the ON...GOSUB target is in the same protected region, an outer 
protected region, or in a non-protected region. 


You cannot specify an ON...GOSUB statement inside a WHEN block 
if the ON...GOSUB target already resides in another protected region 
that does not contain the most current protected region. 


The target cannot be more than 32767 bytes away from the 
ON...GOSUB statement. 


INPUT "Please enter 1, 2 or 3"; A% 

ON A%¥ GOSUB 1000, 2000, 3000, OTHERWISE err_routine 
GOTO done 

PRINT "That was a 1" 

RETURN 

PRINT "That was a 2" 

RETURN 

PRINT "That was a 3" 

RETURN 


err_routine: 
PRINT "Out of range: 


RETURN 


done: 
END PROGRAM 
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ON...GOTO 


ON...GOTO 


The ON...GOTO statement transfers program control to one of several 
lines or targets, depending on the value of a control expression. 


Format 
ON = int-exp 
Syntax Rules 
1. 
yf 
Remarks 
om 
3. 
4. 


GO TO 
target ,... 
GOTO arge [ OTHERWISE target ] 


Int-exp determines which target VAX BASIC selects as the GOTO 
argument. If int-exp equals 1, VAX BASIC selects the first target. If 
int-exp equals 2, VAX BASIC selects the second target, and so on. 


Target must be a valid VAX BASIC line number or a label and must 
exist in the current program unit. 


Control cannot be transferred into a statement block (such as 
FOR...NEXT, UNTIL...NEXT, WHILE...NEXT, DEF...END DEF, 
SELECT...END SELECT, WHEN...END WHEN, or HANDLER...END 
HANDLER). 


If there is an OTHERWISE clause, and if int-exp is less than one or 
greater than the number of targets in the list, VAX BASIC transfers 
control to the target of the OTHERWISE clause. 


If there is no OTHERWISE clause, and if int-exp is less than 1 or 
greater than the number of line numbers in the list, VAX BASIC 
signals “ON statement out of range” (ERR=58). 


If a target specifies a nonexecutable statement, VAX BASIC transfers 
control to the first executable statement that lexically follows the 
target. 


4-248 Statements and Functions 


ON...GOTO 


5. You can only use the ON...GOTO statement inside a handler if all the 
targets are contained within the handler. 


6. You can specify the ON...GOTO statement inside a WHEN block if the 
ON...GOTO target is in the same protected region, an outer protected 
region, or in a non-protected region. 


7. You cannot specify an ON...GOTO statement inside a WHEN block if 
the ON...GOTO target already resides in another protected region that 
does not contain the most current protected region. 


Example 
ON INDEXY GOTO 700,800,900 OTHERWISE finish 


finish: 
END PROGRAM 
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OPEN 


The OPEN statement opens a file for processing. It transfers user-specified 
file characteristics to VAX Record Management Services (RMS) and verifies 
the results. 

Format 


FOR INPUT 
PEN | file- A ILE hni- 
0 ie-spact | FOR INPUT | S [ FILE | [#] chni-exp 


[, open-clause ]... 


open-clause: 


APPEND 
READ 
ACCESS < WRITE 


MODIFY 
SCRATCH 


NONE 


y ) READ 
ALLOW WRITE 


MODIFY 
[ BUFFER int-exp4 | 
[ CONTIGUOUS | 
[ DEFAULTNAME file-spec2 | 
[ EXTENDSIZE int-exp5 | 
[ FILESIZE int-exp2 | 
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OPEN 


[ MAP map-name | 
RELATIVE STREAM 
[ ORGANIZATION | < SEQUENTIAL | VARIABLE | 
UNDEFINED FIXED 
VIRTUAL 


[ RECORDSIZE int-exp? | 


RECORDTYPE FORTRAN 
[ TEMPORARY | 
[ UNLOCK EXPLICIT | 
[ USEROPEN func-name | 
[ WINDOWSIZE int-exp3 | 


Sequential Files Only 


| BLOCKSIZE int-exp8 | 
[| NOREWIND | 

[ NOSPAN | 

[ SPAN | 


Relative and Indexed Files Only 


| BUCKETSIZE int-exp9 | 
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OPEN 


Indexed Files Only 


ALTERNATE [ KEY ] key-clause [ DUPLICATES ] [ CHANGES ] 
| ASCENDING 
DESCENDING 


[ CONNECT chni-exp2 | 


DESCENDING 





PRIMARY [ KEY ] key-clause [ DUPLICATES ] | ASCENDING | | 


int-unsubs-var 
decimal-unsubs-var 


key-clause: str-unsubs-var 
(str-unsubs-var1 ,... str-unsubs-var8 ) 
quad-record-group 
Syntax Rules 


1. File-spec1 specifies the file to be opened and associated with chnl-exp. 
It can be any valid string expression and must be a valid VMS file 
specification. VAX BASIC passes these values to RMS without editing, 
alteration, or validity checks. 


VAX BASIC does not supply any default file specifications, unless you 
include the DEFAULTNAME clause in the OPEN statement. 
2. The FOR clause determines how VAX BASIC opens a file. 


e If you open a file with FOR INPUT, the file must exist or VAX 
BASIC signals an error. 


e If you open a file with FOR OUTPUT, VAX BASIC creates the file 
if it does not exist. If the file does exist, VAX BASIC creates a new 
version of the file. 


e If you do not specify either FOR INPUT or FOR OUTPUT, VAX 
BASIC tries to open an existing file. If there is no such file, VAX 
BASIC creates one. 
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OPEN 


3. Chnl-exp is a numeric expression that specifies a channel number to 
be associated with the file being opened. It can be preceded by an 
optional number sign (#) and must be in the range of 1 through 119. 
Note that channels 100 through 119 are usually reserved for allocation 
by the RTL routines, LIB6GET_LUN and LIBSFREE_LUN. 
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Remarks 


OPEN 


A statement that accesses a file cannot execute until you open that file 
and associate it with a channel. 


The OPEN statement does not retrieve records. 


Channel #0, the terminal, is always open. If you try to open channel 
zero, VAX BASIC signals the error “Illegal I/O channel” (ERR=46). 


If a program opens a file on a channel already associated with an open 
file, VAX BASIC closes the previously opened file and opens the new 
one. 


The ACCESS clause determines how the program can use the file. 


e ACCESS READ allows only FIND, GET, or other input statements 
on the file. The OPEN statement cannot create a file if the 
ACCESS READ clause is specified. 


e ACCESS WRITE allows only PUT, UPDATE, or other output 
statements on the file. 

e ACCESS MODIFY allows any I/O statement except SCRATCH on 
the file. ACCESS MODIFY is the default. 


e ACCESS SCRATCH allows any I/O statement valid for a sequen- 
tial or terminal-format file. 


e ACCESS APPEND is the same as ACCESS WRITE for sequential 
files, except that VAX BASIC positions the file pointer after the last 
record when it opens the file. You cannot use ACCESS APPEND 
on relative or indexed files. 


The ALLOW clause can be used in the OPEN statement to specify file 
sharing of relative, indexed, sequential, and virtual files. 


¢ ALLOW NONE lets no other users access the file. This is the 
default if any access other than READ is specified. Note that you 
must have write access to the file in order to specify ALLOW 
NONE. 


e ALLOW READ lets other users have read access to the file. 
e ALLOW WRITE lets other users have write access to the file. 


e ALLOW MODIFY lets other users have unlimited access to the 
file. 
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OPEN 


10. 


The BLOCKSIZE clause specifies the physical block size of magnetic 
tape files. The BLOCKSIZE clause can be used for magnetic tape files 
only. 


¢ The value of int-exp8 is the number of records in a block. 
Therefore, the block size in bytes is the product of the 
RECORDSIZE and the BLOCKSIZE value. 


e The default blocksize is one record. 


The BUCKETSIZE clause applies only to relative and indexed files. It 
specifies the size of an RMS bucket in terms of the number of records 
one bucket should hold. 


e The value of int-exp9 is the number of records in a bucket. 
e The default is one record. 


The BUFFER clause can be used with all file organizations except 
UNDEFINED. 


e For RELATIVE and INDEXED files, int-exp4 specifies the number 
of device or file buffers RMS uses for file processing. 


e For SEQUENTIAL files, int-exp4 specifies the size of the buffer; for 
example, BUFFER 8 for a SEQUENTIAL file sets the buffer size to 
eight 512-byte blocks. 


e DIGITAL recommends that you accept the system defaults or 
change the defaults with the DCL SET RMS_DEFAULT command. 


The CONTIGUOUS clause causes RMS to try to create the file as 
a contiguous-best-try sequence of disk blocks. The CONTIGUOUS 
clause does not affect existing files or nondisk files. 


The CONTIGUOUS clause does not guarantee that the file will occupy 
contiguous disk space. If RMS can locate the file in a contiguous area, 
it will do so. However, if there is not enough free contiguous space 
for a file, RMS allocates the largest possible contiguous space and does 
not signal an error. See the VAX Record Management Services Reference 
Manual for more information on contiguous disk allocation. 


The CONNECT clause permits multiple record streams to be con- 

nected to the file. 

e The CONNECT clause must specify an INDEXED file already 
opened on chnl-exp2 with the primary OPEN statement. 


e You cannot connect to a connected channel; you can connect only 
to the initially opened channel. 
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OPEN 


e You can connect more than one stream to an open channel. 


e §6All clauses of the two files to be connected must be identical 
except MAP, CONNECT, and USEROPEN. 


e Do not use the CONNECT clause when accessing files over 
DECnet or VAX BASIC will signal the error “Cannot open file” 
(ERR=162). 


11. The DEFAULTNAME clause lets you supply a default file specifica- 
tion. If file-spec1 is not a complete file specification, file-spec2 in the 
DEFAULTNAME clause supplies the missing parts. For example: 


10 INPUT 'FILE NAME' ; fnam$ 
20 OPEN fnam$ FOR INPUT AS FILE #1%, & 
DEFAULTNAME "USER$$DISK: . DAT" 


If you type “ABC” for the file name, VAX BASIC tries to open 
USER$$DISK;[]ABC.DAT. 


12. The EXTENDSIZE clause lets you specify the increment by which 
RMS extends a file after its initial allocation is filled. The value of 
int-exp5 is in 512-byte disk blocks. The EXTENDSIZE clause has no 
effect on an existing file. 


13. The FILESIZE clause lets you pre-extend a new file to a specified 
size. 


e The value of int-exp2 is the initial allocation of disk blocks. 
e The FILESIZE clause has no effect on an existing file. 


14. The MAP clause specifies that a previously declared map is associated 
with the file’s record buffer. The MAP clause determines the record 
buffer’s address and length unless overridden by the RECORDSIZE 
clause. 


e The size of the specified map must be as large or larger than the 
longest record length or maximum record size. For files with a 
fixed record size, the specified map must match exactly. 


e The size of the largest MAP with the same map name in the 
current program unit becomes the file’s record size if the OPEN 
statement does not include a RECORDSIZE clause. 


e DIGITAL recommends that you do not use both the MAP and 
RECORDSIZE clauses in an OPEN statement. However, if you 
do use both the MAP and RECORDSIZE clauses in an OPEN 
statement, the following rules apply: 


— The RECORDSIZE clause overrides the record size set by the 
MAP clause. 


July 1988 Statements and Functions 4-255 


OPEN 


— The map must be as large or larger than the specified 
RECORDSIZE. 


e If there is no MAP clause, the record buffer space that VAX BASIC 
allocates is not directly accessible. Therefore, MOVE statements 
are needed to access data in the record buffer. 


e You must have a MAP clause when creating an indexed file; you 
cannot use KEY clauses without MAP statements because keys 
serve as offsets into the buffer. 


e The size of the specified map cannot exceed 32767 bytes. 


15. The NOREWIND clause controls tape positioning on magnetic tape 
files. The NOREWIND clause can be used for magnetic tape files only. 


e If you specify NOREWIND, the OPEN statement does not position 
the tape at the beginning. Your program can search for records 
from the current position. 


e If you do not specify either ACCESS APPEND or NOREWIND, 
the OPEN statement positions the tape at its beginning and then 
searches for the file. 


16. The NOSPAN clause specifies that sequential records cannot cross 
block boundaries. 


¢ SPAN specifies that records can cross block boundaries. SPAN is 
the default. 


e The NOSPAN clause does not affect nondisk files. 


17. The ORGANIZATION clause specifies the file organization. When 
present, it must precede all other clauses. When you specify an 
ORGANIZATION clause, you must also specify one of the fol- 
lowing organization options: VIRTUAL, UNDEFINED, INDEXED, 
SEQUENTIAL or RELATIVE. Specify ORGANIZATION UNDEFINED 
if you do not know the actual organization of the file. If you do not 
specify an ORGANIZATION clause VAX BASIC opens a terminal 
format file by default. 


e When you specify ORGANIZATION VIRTUAL, you create a 
sequentially fixed file with a record size of 512 (or a multiple of 
512). You can then access the file with the FIND, GET, PUT, 
or UPDATE statements or through one or more virtual arrays. 
VAX BASIC allows you to overwrite existing records in a file 
not containing virtual arrays and opened as ORGANIZATION 
VIRTUAL by using the PUT statement with a RECORD clause. 
All other organizations require the UPDATE statement to change 
an existing record. DIGITAL recommends that you also use the 
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UPDATE statement to change existing records in VIRTUAL files 

that do not contain virtual arrays. 

¢ When you do not know the organization of a file, you can open 
a file for input and specify ORGANIZATION UNDEFINED. 

You can then use the FSP$ function or a USEROPEN routine 

to determine the attributes of the file. You will usually want to 

specify the RECORDTYPE ANY clause with the ORGANIZATION 

UNDEFINED clause. The combination of these two clauses should 

allow you to access any file sequentially. 

e When you specify ORGANIZATION INDEXED, you create an 
indexed file whose data records are sorted in ascending or de- 
scending order according to a primary index key value. 

— The index keys you specify determine the order in which 
records are stored. 

— Index keys must be variables declared in a MAP statement 
associated with the OPEN statement for the file. 

— VAX BASIC allows you to specify an indexed file as either 
variable or fixed length. 

e When you specify ORGANIZATION SEQUENTIAL, you create a 
file that stores records in the order that they are written. 

— Sequential files can contain records of any valid VAX BASIC 
record format: fixed-length, variable-length, or stream. 

— If you open an existing file using stream as a record format 
option, the file must be one of the following stream record 
formats defined by RMS: 
e¢ STREAM records can be delimited by any special 

character. 


e STREAM_LF must be delimited by a line-feed character. 
¢ STREAM_CR must be delimited by a carriage return. 


If the file is not one of these stream formats, VAX BASIC sig- 
nals the error “RECATTNOT, record attributes not matched”. 


e When you specify ORGANIZATION RELATIVE, you create a file 
that contains a series of records that are numbered consecutively. 
VAX BASIC allows you to specify either fixed-length or variable- 
length records. 
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If you omit the ORGANIZATION clause entirely, a terminal- 
format file is opened. 


— Terminal-format files are implemented as RMS sequential 
variable files and store ASCII characters in variable-length 
records. 


— Carriage control is performed by the operating system; the 
record does not contain carriage returns or line feeds. 


— You use essentially the same syntax to access terminal-format 
files as when reading from or writing to the terminal (INPUT 
and PRINT). 


18. The PRIMARY KEY clause lets you specify an indexed file’s key. 
You must specify a primary key when opening an indexed file. The 
ALTERNATE KEY clause lets you specify up to 254 alternate keys. 
The ALTERNATE KEY clause is optional. 


RMS creates one index list for each primary and alternate key you 
specify. These indexes are part of the file and contain pointers to 
the records. Each key you specify corresponds to a sorted list of 
record pointers. 


You can specify each key as ASCENDING or DESCENDING; 
ASCENDING is the default. In an ASCENDING key, lower 

key values occur toward the beginning of the index. In a 
DESCENDING key, higher key values occur toward the beginning 
of the index. 


The keys you specify determine the order in which records in the 
file are stored. All keys must be variables declared in the file’s 
corresponding MAP statement. The position of the key in the 
MAP statement determines its position in the record. The data 
type and size of the key are as declared in the MAP statement. 


A key can be an unsubscripted string, a WORD, LONG, or packed 
decimal variable, or a record or group which is exactly eight bytes 
long. 


You can also create a segmented index key for string keys by 
separating the string variable names with commas and enclosing 
them in parentheses. You can then reference a segment of the 
specified key by referencing one of the string variables instead of 
the entire key. A string key can have up to eight segments. 


The order of appearance of keys determines key numbers. The 
primary key, which must appear first, is key #0. The first alternate 
key is #1, and so on. 
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e DUPLICATES in the PRIMARY and ALTERNATE key clauses 
specifies that two or more records can have the same key value. If 
you do not specify DUPLICATES, the key value must be unique 
in all records. 


e CHANGES in the ALTERNATE KEY clause specifies that you can 
change the value of an alternate key when updating records. If 
you do not specify CHANGES when creating the file, you cannot 
change the value of a key. You cannot specify CHANGES with 
the PRIMARY KEY clause. 

e KEY clauses are optional for existing files. If you do specify a key, 
it must match a key in the file. 


19. The RECORDTYPE clause specifies the file’s record attributes. 


e LIST specifies implied carriage control, <CR> . This is the 
default for all file organizations except VIRTUAL. 
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FORTRAN specifies a control character in the record’s first byte. 


NONE specifies no attributes. This is the default for VIRTUAL 
files. 


If you open a terminal-format file with RECORDTYPE NONE, you 
must explicitly insert carriage control characters into the records 
your program writes to the file. 


ANY specifies a match with any file attributes when opening an 
existing file. If you create a new file, ANY is treated as LIST for 
all organizations except VIRTUAL. For VIRTUAL, it is treated as 
NONE. 


20. The RECORDSIZE clause specifies the file’s record size. Note that 
there are restrictions on the maximum record size allowed for various 
file and record formats. See the VAX Record Management Services 
Reference Manual for more information. 


For fixed-length records, int-exp1 specifies the size of all records. 


For variable-length records, int-exp1 specifies the size of the largest 
record. 


DIGITAL recommends that you do not use both the MAP and 
RECORDSIZE clauses in an OPEN statement. However, if you 
do use both the MAP and RECORDSIZE clauses in an OPEN 
statement, the following rules apply: 


— The RECORDSIZE clause overrides the record size set by the 
MAP clause. 

— The map must be as large or larger than the specified 
RECORDSIZE. 

If you specify a MAP clause but no RECORDSIZE clause, the 

record size is equal to the map size. 

If there is no MAP clause, the RECORDSIZE clause determines 

the record size. 


When creating a relative or indexed file, you must specify either a 
MAP or RECORDSIZE clause. Otherwise, VAX BASIC signals an 
error. 


For fixed files, the record size must match exactly. 


If you do not specify a RECORDSIZE clause when opening an 
existing file, VAX BASIC retrieves the record size value from the 
file. 
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e When you print to a terminal-format file, you must supply a 
record size if the margin is to exceed 72 characters. For example, 
if you want to print a 132-character line, specify RECORDSIZE 
132 or use the MARGIN and NOMARGIN statements. 


e When creating SEQUENTIAL files, VAX BASIC supplies a default 
record size of 132. 


e The record size is always 512 for VIRTUAL files, unless you 
specify a RECORDSIZE. 


21. The TEMPORARY clause causes VAX BASIC to delete the output file 
as soon as the program closes it. 


22. The UNLOCK EXPLICIT clause allows you to retain locks on records 
until they are explicitly unlocked. 


e The type of lock you impose on a record with a GET or FIND 
statement remains in effect until you explicitly unlock the record 
or file with a FREE or UNLOCK statement or until you close the 
file. 

e If you specify UNLOCK EXPLICIT, and do not specify an ALLOW 
clause with a GET or FIND statement, VAX BASIC imposes 
the ALLOW NONE lock by default and the next GET or FIND 
operation does not unlock the previously locked record. 


e You must open a file with UNLOCK EXPLICIT before you can 
explicitly lock records with the ALLOW clause on GET and FIND 
statements. See the sections on GET and FIND in this manual 
and the VAX BASIC User Manual for more information on explicit 
record locking and unlocking. 


23. The USEROPEN clause lets you open a file with your own 
FUNCTION subprogram. 


e¢ Func-name must be a separately compiled FUNCTION subprogram 
and must conform to FUNCTION statement rules for naming 
subprograms. 


e You do not need to declare the useropen routine as an external 
function. 


e VAX BASIC calls the user program after it fills the FAB (File Access 
Block), the RAB (Record Access Block), and the XABs (Extended 
Attribute Blocks). The subprogram must issue the appropriate 
RMS calls, including $OPEN and $CONNECT, and return the 
RMS status as the value of the function. See the VAX BASIC User 
Manual for more information on the USEROPEN routine. 
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Examples 


OPEN 


NOTE 


Future releases of the Run-Time Library may alter the 
use of some VAX RMS fields. Therefore, you may have 
to alter your USEROPEN procedures accordingly. 


24. The WINDOWSIZE clause followed by int-exp3 lets you specify the 
number of block retrieval pointers you want to maintain in memory 
for the file. 


Retrieval pointers are associated with the file header and point to 
contiguous blocks on disk. 


By keeping retrieval pointers in memory you can reduce the I/O 
associated with locating a record, as the operating system dces not 
have to access the file header for pointers as frequently. 


The number of retrieval pointers in memory at any one time is 
determined by the system default or by the WINDOWSIZE clause. 


The default number of retrieval pointers on VAX/VMS systems 
is 7. 
A value of zero specifies the default number of retrieval pointers. 


A value of -1 means to map the entire file, if possible. Vaiues 
from -128 through -2 are reserved. 


Example 1 


OPEN "FILE.DAT" AS FILE #4 


Example 2 


OPEN "INPUT.DAT" FOR INPUT AS FILE #4, 


OPEN Newfile$ FOR OUTPUT AS FILE #3, 


ORGANIZATION SEQUENTIAL FIXED, 
RECORDSIZE 200, 

MAP ABC, 

ALLOW MODIFY, ACCESS MODIFY 


See & 


INDEXED VARIABLE, 

MAP Emp_name, 

DEFAULTNAME "USER$$DISK: .DAT", 
PRIMARY KEY Last$ DUPLICATES, 
ALTERNATE KEY First$ CHANGES 


Pere & 
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MAP (SEGKEY) STRING last_name = 15, & 
MI = 1, first_name = 15 


OPEN "NAMES.IND" FOR OUTPUT AS FILE #1, 
ORGANIZATION INDEXED, 
PRIMARY KEY (last_name, first_name, MI), 
MAP SEGKEY 


BR B & 


Example 3 


MAP (OWNERKEYS) STRING owner_id = 6, dog_reg_no = 7, & 
last_name = 25, first_name = 20 


OPEN "QWNERS.IND" FOR OUTPUT AS FILE #1, 
ORGANIZATION INDEXED, 
PRIMARY KEY (owner_id), 
ALTERNATE KEY (last_name) DUPLICATES CHANGES, 
ALTERNATE (dog_reg_no) DESCENDING, 
MAP OWNERKEYS 


Rk & & & 


The MAP statement describes the three string variables used as index keys 
in the file OWNERS.IND. The OPEN statement declares an indexed file 
with two alternate keys in addition to the primary key. The alternate key 
dog_reg_no is a DESCENDING key; the other keys are ASCENDING by 
default. 
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OPTION 


The OPTION statement allows you to set compilation qualifiers such as 
default data type, size, and scale factor. You can also set compilation 
conditions such as severity of run-time errors to handle, constant type 
checking, subscript checking, overflow checking, decimal rounding, and 
setup in a source program. The options you set affect only the program 
module in which the OPTION statement occurs. 


Format 


OPTION  option-clause.... 


ANGLE=angle-clause 
HANDLE=handle-clause 
CONSTANT TYPE =const-type-clause 
OLD VERSION = CDD 

option-clause: TYPE=type-clause 
SIZE=size-clause 
SCALE=/nt-const 


{ ACTIVE 


INACTIVE } = active-clause 


angle-clause: \ DEGREES 


RADIANS 


BASIC 

SEVERE 
handle-clause: ERROR 

WARNING 

INFORMATIONAL 
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REAL 
const-type-clause? INTEGER 


DECIMAL 


INTEGER 
REAL 

EXPLICIT 
DECIMAL 


type-clause: 


F size-item 
size-clause: 


(size-item,...) 


REAL real-clause 
DECIMAL(d,s) 


size-item: 


int-clause: WORD 


BYTE 
LONG 


SINGLE 

DOUBLE 
GFLOAT 
HFLOAT 


real-clause: 


active-clause: 


| 
| 
( 
| 
| 
| 


active-item } 
(active-item,...) 
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active-item: 


Syntax Rules 


Remarks 


None. 


OPTION 


INTEGER OVERFLOW 
DECIMAL OVERFLOW 
SETUP 

DECIMAL ROUNDING 
SUBSCRIPT CHECKING 


1. Option-clause specifies the compilation qualifiers to be in effect for 
the program module. 


2. Angle-clause specifies whether angles are to be evaluated in radians 
or in degrees. If you do not specify an angle-clause, VAX BASIC uses 
radians as the default. 


3. Handle-clause specifies the severity level of the errors which are to be 
handled by an error handler. 


If you do not specify an OPTION HANDLE statement, VAX 
BASIC uses OPTION HANDLE = BASIC as the default. Only 
those errors that are trappable and that map onto a VAX BASIC 
ERR value will transfer control to the current error handler. See 
the VAX BASIC User Manual for a list of VAX BASIC run-time 
errors. 


If you specify a severity level, all trappable and non-trappable 
errors of the specified severity or less transfer control to the cur- 
rent error handler. This includes non-BASIC errors. For example, 
OPTION HANDLE = ERROR implies ERROR, WARNING, and 
INFORMATIONAL errors but not SEVERE errors. 


If you specify OPTION HANDLE = SEVERE, you can handle 
fatal errors. However, in most cases, a fatal error indicates that 
the program environment is badly corrupted and you should not 
continue program execution. 
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10. 


11. 


12, 


13: 


Const-type-clause specifies the data type for all constants that do not 
end in a data type suffix or are not in explicit literal notation with a 
data type supplied. 


Type-clause sets the default data type for variables that have not 
been explicitly declared and for constants if no constant type clause is 
specified. You can specify only one type-clause in a program module. 


Size-clause sets the default data subtypes for floating-point, integer, 
and packed decimal data. Size-item specifies the data subtype you 
want to set. You can specify an INTEGER, REAL or DECIMAL size- 
item, or an combination. Multiple size-items in an OPTION statement 
must be enclosed in parentheses and separated by commas. 


SCALE controls the scaling of double precision floating-point vari- 
ables. Int-const specifies the power of 10 you want as the scaling 
factor. It must be an integer between 0 and 6 or VAX BASIC signals 
an error. See the description of the SCALE command in Chapter 2 of 
this manual for more information on scaling. 


OLD VERSION = CDD is provided for compatibility with previous 
versions of BASIC. When bounds are specified in the CDD array, VAX 
BASIC changes the lower bound to zero and adjusts the upper bound 
of the array. By default, if you do not specify OLD VERSION = CDD, 
VAX BASIC compiles the program with the bounds specified in the 
CDD data definition. 


Active-clause specifies the decimal rounding, integer and decimal 
overflow checking, setup, and subscript checking conditions you want 
in effect for the program module. Active-item specifies the conditions 
you want to set. Multiple active-items in an OPTION statement must 
be enclosed in parentheses and separated by commas. 


You can have more than one option in an OPTION statement, or you 
can use multiple OPTION statements in a program module. However, 
each OPTION statement must lexically precede all other source code 
in the program module, with the exception of comment fields, REM, 
PICTURE, PROGRAM, SUB, FUNCTION, and OPTION statements. 


OPTION statement specifications apply only to the program module 
in which the statement appears and affect all variables in the module, 
including SUB and FUNCTION parameters. 


VAX BASIC signals an error in the case of conflicting options. For 
example, you cannot specify more than one type-clause or SCALE 
factor in the same program unit. 


If you do not specify a type-clause or a subtype-clause, VAX BASIC 
uses the current environment default data types. 
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14. If you do not specify a scale factor, VAX BASIC uses the current 
environment default scale factor. 


15. ACTIVE specifies the conditions that are to be in effect for a particular 
program module. INACTIVE specifies the conditions that are not to 
be in effect for a particular program module. If a condition does not 
appear in an active-clause, VAX BASIC uses the current environment 
default for the condition. 


See the description of the COMPILE command in Chapter 2 of this 
manual and the VAX BASIC User Manual for more information on the 
INTEGER_OVERFLOW, DECIMAL_OVERFLOW, SETUP, DECIMAL — 
ROUNDING, and SUBSCRIPT_CHECKING compilation qualifiers. 
These qualifiers correspond to active-clause conditions (INTEGER 
OVERFLOW, DECIMAL OVERFLOW, SETUP, DECIMAL ROUNDING, 
and SUBSCRIPT CHECKING). 


FUNCTION REAL DOUBLE monthly_payment, 
(DOUBLE interest_rate, 
LONG no_of_payments, 
DOUBLE principle) 
OPTION TYPE = REAL, 
SIZE = (REAL DOUBLE, INTEGER LONG), 
SCALE = 4 


& & & 


& & 
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The PLACE$ function explicitly changes the precision of a numeric string. 
PLACE$ returns a numeric string, truncated or rounded, according to the 
value of an integer argument you supply. 


Format 


str-var = PLACES$ (str-exp, int-exp) 
Syntax Rules 


1. Str-exp specifies the numeric string you want to process. It can have 
one of the following: 


e An optional minus sign (—), ASCII digits, and an optional decimal 
point (.) 

e An optional minus sign, ASCII digits, an optional decimal point, 
the letter E, an optional minus sign, and a 2-digit exponent 


2. Int-exp specifies the numeric precision of str-exp. Table 4-5 shows 
examples of rounding and truncation and the values of int-exp that 
produce them. 


Remarks 


1. If str-exp has more than 60 characters, VAX BASIC signals the error 
“Illegal number” (ERR=52). 


2. Str-exp is rounded or truncated, or both, according to the value of 
int-exp. 

3. If int-exp is between —60 and 60, rounding and truncation occur as 
follows: 


e For positive integer expressions, rounding occurs to the right of 
the decimal place. For example, if int-exp is 1, rounding occurs 
one digit to the right of the decimal place (the number is rounded 
to the nearest tenth). If int-exp is 2, rounding occurs two digits 
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Table 4—5: 
Int-exp 

-5 

-4 

-3 


PLACES 


to the right of the decimal place (the number is rounded to the 
nearest hundredth), and so on. 


If int-exp is zero, VAX BASIC rounds to the nearest unit. 


For negative integer expressions, rounding occurs to the left of the 
decimal point. If int-exp is -1, for example, VAX BASIC moves the 
decimal point one place to the left, then rounds to units. If int-exp 
is -2, rounding occurs two places to the left of the decimal point; 
VAX BASIC moves the decimal point two places to the left, then 
rounds to tens. 


4. If int-exp is between 9940 and 10,060, truncation occurs as follows: 


If int-exp is 10,000, VAX BASIC truncates the number at the 
decimal point. 


If int-exp is greater than 10,000 (10,000 plus n) VAX BASIC 
truncates the numeric string n places to the right of the decimal 
point. For example, if int-exp is 10,001 (10,000 plus 1), VAX 
BASIC truncates the number starting one place to the right of the 
decimal point. If int-exp is 10,002 (10,000 plus 2), VAX BASIC 
truncates the number starting two places to the right of the 
decimal point, and so on. 


If int-exp is less than 10,000 (10,000 minus n), VAX BASIC trun- 
cates the numeric string n places to the left of the decimal point. 
For example, if int-exp is 9999 (10,000 minus 1), VAX BASIC 
truncates the number starting one place to the left of the decimal 
point. If 9998 (10,000 minus 2), VAX BASIC truncates starting two 
places to the left of the decimal point, and so on. 


5. If int-exp is not between -60 and 60 or 9940 and 10,060, VAX BASIC 
returns a value of zero. 


6. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


7. Table 4-5 shows examples of rounding and truncation and the values 
of int-exp that produce them. The number used is 123456.654321: 


Rounding and Truncation of 123456.654321 


Effect Value Returned 
Rounded to 100,000s and truncated 1 

Rounded to 10,000s and truncated 12 

Rounded to 1000s and truncated 125 
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Table 4—5 (Cont.): 


Int-exp 


9,995 
9,996 
9,997 
9,998 
9,999 
10,000 
10,001 
10,002 
10,003 
10,004 
10,005 


Effect 


Rounded to 100s and truncated 

Rounded to 10s and truncated 

Rounded to units and truncated 

Rounded to tenths and truncated 

Rounded to hundredths and truncated 
Rounded to thousandths and truncated 
Rounded to ten-thousandths and truncated 
Rounded to hundred-thousandths and truncated 
Truncated to 100,000s 

Truncated to 10,000s 

Truncated to 1000s 

Truncated to 100s 

Truncated to 10s 

Truncated to units 

Truncated to tenths 

Truncated to hundredths 

Truncated to thousandths 

Truncated to ten-thousandths 

Truncated to hundred-thousandths 


DECLARE STRING str_exp, str_var 
str_exp = "9999.9999" 

str_var = PLACE$(str_exp, 3) 
PRINT str_var 


Output 
10000 
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Rounding and Truncation of 123456.654321 


Value Returned 


1235 

12346 

123457 
123456.7 
123456.65 
123456.654 
123456.6543 
123456.65432 
1 

12 

123 

1234 

12345 

123456 
12345.6 
123456.65 
123456.654 
123456.6543 
123456.65432 


POS 


POS 


The POS function searches for a substring within a string and returns the 
substring’s starting character position. 


Format 


int-var = POS (str-exp1, str-exp2, int-exp) 
Syntax Rules 


1. Str-exp1 specifies the main string. 
Str-exp2 specifies the substring. 


3. Int-exp specifies the character position in the main string at which 
VAX BASIC starts the search. 


Remarks 


1. The POS function searches str-exp1, the main string, for the first 
occurrence of str-exp2, the substring, and returns the position of the 
substring’s first character. 


2. If int-exp is greater than the length of the main string, POS returns a 
value of zero. 


3. POS always returns the character position in the main string at which 
VAX BASIC finds the substring, with the following exceptions: 


e If only the substring is null, and if int-exp is less than or equal to 
zero, POS returns a value of 1. 


e If only the substring is null, and if int-exp is equal to or greater 
than 1 and less than or equal to the length of the main string, 
POS returns the value of int-exp. 


e If only the substring is null and if int-exp is greater than the length 
of the main string, POS returns the main string’s length plus 1. 
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e If only the main string is null, POS returns a value of zero. 

e If both the main string and the substring are null, POS returns 1. 
4. If VAX BASIC cannot find the substring, POS returns a value of zero. 
5. If int-exp is less than 1, VAX BASIC assumes a starting position of 1. 


If int-exp does not equal 1, VAX BASIC still counts from the string’s 
beginning to calculate the starting position of the substring. That 
is, VAX BASIC counts character positions starting at position 1, 
regardless of where you specify the start of the search. For example, 
if you specify 10 as the start of the search and VAX BASIC finds the 
substring at position 15, POS returns the value 15. 


7. If you know that the substring is not near the beginning of the string, 
specifying a starting position greater than 1 speeds program execution 
by reducing the number of characters VAX BASIC must search. 


8. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


DECLARE STRING main_str, & 
sub_str 
DECLARE INTEGER first_char 
Main_str = "ABCDEFG" 
sub_str = "DEFG" 
first_char = POS(main_str, sub_str, 1) 
PRINT first_char 


Output 


4 
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PRINT 


The PRINT statement transfers program data to a terminal or a terminal- 
format file. 


Format 
PRINT [ #chnl-exp, ] [ output-list ] 


output-list: [ exp ] [ { } exp J... E | 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). If you do not specify a channel, VAX BASIC prints to the 
controlling terminal. 


2. Output-list specifies the expressions to be printed and the print format 
to be used. 


3. Exp can be any valid expression. 


4. A separator character (comma or semicolon) must separate each exp. 
Separator characters control the print format as follows: 


e Acomma (,) causes VAX BASIC to skip to the next print zone 
before printing the expression. 


e A semicolon (;) causes VAX BASIC to print the expression imme- 
diately after the previous expression. 
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Remarks 


1. A terminal or terminal-format file must be open on the specified 
channel. (Your current terminal is always open on channel #0.) 


2. A PRINT line has an integral number of print zones. Note, however, 
that the number of print zones in a line differs from terminal to 
terminal. 


3. The right margin setting, if set by the MARGIN statement, controls 
the width of the PRINT line. The default right margin is 72. 


4. The PRINT statement prints string constants and variables exactly as 
they appear, with no leading or trailing spaces. 


5. VAX BASIC prints quoted string literals exactly as they appear. 
Therefore, you can print quotation marks, commas, and other charac- 
ters by enclosing them in quotation marks. 


A PRINT statement with no output-list prints a blank line. 


An expression in the output-list can be followed by more than one 
separator character. That is, you can omit an expression and specify 
where the next expression is to be printed by the use of multiple 
separator characters. For example: 


PRINT "Name", ,"Address and ";"City" 


Output 


Name Address and City 


In this example, the double commas after “Name” cause VAX BASIC 
to skip two print zones before printing “Address and ”. The semicolon 
causes the next expression, “City”, to be printed immediately after the 
preceding expression. Multiple semicolons have the same effect as a 
single semicolon. 


8. When printing numeric fields, VAX BASIC precedes each number with 
a space or minus sign (—) and follows it with a space. 


9. VAX BASIC does not print trailing zeros to the right of the decimal 
point. If all digits to the right of the decimal point are zeros, VAX 
BASIC omits the decimal point as well. 


10. For REAL numbers (SINGLE, DOUBLE, GFLOAT, and HFLOAT), 
VAX BASIC does not print more than six digits in explicit notation. 
If a number requires more than six digits, VAX BASIC uses E format 
and precedes positive exponents with a plus sign (+). VAX BASIC 
rounds a floating-point number with a magnitude between 0.1 and 1.0 
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LL; 


12: 


13. 


14. 


PRINT 


to six digits. For magnitudes smaller than 0.1, VAX BASIC rounds the 
number to six digits and prints it in E format. 

The PRINT statement can print up to 

¢ 3 digits of precision for BYTE integers 

e 5 digits of precision for WORD integers 

¢ 10 digits of precision for LONG integers 

¢ 31 digits of precision for DECIMAL numbers 

¢ The string length for STRING values 


VAX BASIC prints both INTEGER and DECIMAL values according to 
the previous rules. However, for REAL values, VAX BASIC displays a 
maximum of 6 digits. 


If there is a comma or semicolon following the last item in output-list, 
VAX BASIC does the following: 


e When printing to a terminal, VAX BASIC does not generate a 
line terminator after printing the last item. The next item printed 
with a PRINT statement is printed at the position specified by 
the separator character following the last item in the first PRINT 
statement. 


e When printing to a terminal-format file, VAX BASIC does not 
write out the record until a PRINT statement without trailing 
punctuation executes. 

If no punctuation follows the last item in the output-list VAX BASIC 

does the following: 

¢ When printing to a terminal, VAX BASIC generates a line termina- 
tor after printing the last item. 

¢ When printing to a terminal-format file, VAX BASIC writes out the 
record after printing the last item. 

If a string field does not fit on the current line VAX BASIC does the 

following: 

¢ When printing string elements to a terminal, VAX BASIC prints as 
much as will fit on the current line and prints the remainder on 
the next line. 

e When printing string elements to a terminal-format file, VAX 
BASIC prints the entire element on the next line. 
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15. If a numeric field is the first field in a line, and the numeric field spans 
more than one line, VAX BASIC prints part of the number on one line 
and the remainder on the next. Otherwise, numeric fields are never 
split across lines. If the entire field cannot be printed at the end of one 
line, the number is printed on the next line. 


16. When a number’s trailing space does not fit in the last print zone, the 
number is printed without the trailing space. 


Example 
PRINT “name "; "age", "height "; "weight" 
Output 
name age height weight 
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PRINT USING 


The PRINT USING statement generates output formatted according to a 
format string (either numeric or string) to a terminal or a terminal-format 
file. 


Format 


PRINT / #chnl-exp ] USING str-exp { ; output-list 


I 
. 
' 


output-list: [exp] [ { \ exp J... i | 


tl 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). If you do not specify a channel, VAX BASIC prints to the 
controlling terminal. 


2. Str-exp is the format string. It must contain at least one valid format 
field and must be followed by a separator (comma or semicolon) and 
at least one expression. 


NOTE 


DIGITAL recommends that you use compile-time constant 
expressions for str-exp whenever possible. When you 

do this, the VAX BASIC compiler compiles the string at 
compilation time rather than at run time, thus improving 
the performance of your program. 


3. Output-list specifies the expressions to be printed. 
e Exp can be any valid expression. 
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Remarks 


A comma or semicolon must separate each expression. 


A comma or semicolon is optional after the last expression in the 
list. 


1. The PRINT USING statement can print up to 


Three digits of precision for BYTE integers 

Five digits of precision for WORD integers 

Six digits of precision for SINGLE floating-point numbers 

Ten digits of precision for LONG integers 

Sixteen digits of precision for DOUBLE floating-point numbers 
Fifteen digits of precision for GFLOAT floating-point numbers 


Thirty-three digits of precision for HFLOAT floating-point num- 
bers 


Thirty-one digits of precision for DECIMAL numbers 
The string length for STRING values 


2. A terminal or terminal-format file must be open on the specified 
channel or VAX BASIC signals an error. 


3. The separator characters (comma or semicolon) in the PRINT USING 
statement do not control the print format as in the PRINT statement. 
The print format is controlled by the format string. Therefore, it does 
not matter whether you use a comma or semicolon. 


4. Formatting Numeric Output 


The number sign (#) reserves space for one sign or digit. 


The comma (,) causes VAX BASIC to insert commas before every 
third significant digit to the left of the decimal point. In the format 
field, the comma must be to the left of the decimal point, and to 
the right of the rightmost dollar sign, asterisk, or number sign. A 
comma reserves space for a comma or digit. 


The period (.) inserts a decimal point. The number of reserved 
places on either side of the period determines where the decimal 
point appears in the output. 
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e The hyphen (-) reserves space for a sign and specifies trailing 
minus sign format. If present, it must be the last character in 
the format field. It causes VAX BASIC to print negative numbers 
with a minus sign after the last digit, and positive numbers with a 
trailing space. The hyphen (-) can be used as part of a dollar sign 
($$) format field. 


¢ The letters CD (Credit/Debit) enclosed in angle brackets 
( <CD> ) print CR (Credit Record) after negative numbers or zero 
and DR (Debit Record) after positive numbers. If present, they 
must be the last characters in the format field. The Credit/Debit 
format can be used as part of a dollar sign ($$) format field. 


e Four carets(“*"*) specify E notation for floating-point and 
DECIMAL numbers. They reserve four places for SINGLE, 
DOUBLE, GFLOAT, and DECIMAL values and five places for 
HFLOAT values. If present, they must be the last characters in the 
format field. 


¢ Two dollar signs ($$) reserve space for a dollar sign and a digit 
and cause VAX BASIC to print a dollar sign immediately to the 
left of the most significant digit. 


e Two asterisks (**) reserve space for two digits and cause VAX 
BASIC to fill the left side of the numeric field with leading aster- 
isks. 


¢ A zero enclosed in angle brackets (<0> ) prints leading zeros 
instead of leading spaces. 


e A percent sign enclosed in angle brackets ( <%> ) prints all 
spaces in the field if the value of the print item is zero. 


NOTE 


You cannot specify the dollar sign ($$), asterisk-fill 
(**), and zero-fill (<0O> ) formats within the same 
print field. Similarly, VAX BASIC does not allow you 
to specify the zero-fill (<0O> ) and the blank-if-zero 
( <%> ) formats within the same print field. 


e An underscore (_) forces the next formatting character in the 
format string to be interpreted as a literal. It affects only the next 
character. If the next character is not a valid formatting character, 
the underscore has no effect and will itself be printed as a literal. 


5. VAX BASIC interprets any other characters in a numeric format string 
as string literals. 
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Depending on usage, the same format string characters can be com- 
bined to form one or more print fields within a format string. For 
example: 


When a dollar sign ($$) or asterisk-fill (**) format precedes 

a number sign (#) , it modifies the number sign format. The 
dollar sign or asterisk-fill format reserves two places, and with the 
number signs forms one print field. For example: 


S$$H#H## Forms one field and reserves five spaces 


+a Forms one field and reserves four spaces 


When these formats are not followed by a number sign or a 
blank-if-zero (<%-> ) format, they reserve two places and form a 
separate print field. 


When a zero-fill (<0> ) or blank-if-zero format precedes a 
number sign, it modifies the number sign format. The <0O> or 

<%-> _ reserves one place, and with the number signs forms one 
print field. For example: 


<0O> #### Forms one field and reserves five spaces 


<%> ##H# Forms one field and reserves four spaces 


When these formats are not followed by a number sign, they 
reserve one space and form a separate print field. 

When a blank-if-zero (<%-> ) format follows a dollar sign or 
asterisk-fill format (**), it modifies the dollar sign ($$) or asterisk 
fill (**) format string. The blank-if-zero reserves one space, 

and with the dollar signs or asterisks forms one print field. For 
example: 


$$ <%> ### Forms one field and reserves six spaces 


ae <% > ## Forms one field and reserves five spaces 


When the blank-if-zero precedes the dollar signs or asterisks, it 
reserves one space and forms a separate print field. 


The comma (digit separator), dollar sign (currency symbol), and 


decimal point (radix point) are the defaults for U.S. currency. On 
VAX/VMS systems, you can change the digit separator, currency 
symbol and radix point by assigning the logical names SYS$DIGIT_ 
SEP, SYS$6CURRENCY and SYS$RADIX—POINT. Once you make 
each assignment, the PRINT USING statement accesses these logical 
names for these symbols. 
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12. 


13. 


14. 


PRINT USING 


For E notation, PRINT USING left-justifies the number in the format 
field and adjusts the exponent to compensate, except when printing 
zero. When printing zero in E notation, VAX BASIC prints leading 
spaces, leading zeros, a decimal point, and zeros in the fractional por- 
tion if the PRINT USING string contains these formatting characters, 
and then the string “E+00”. 


Zero cannot be negative. If a small negative number rounds to zero, it 
is represented as a positive zero. 


If there are reserved positions to the left of the decimal point, and the 
printed number is less than 1, VAX BASIC prints one zero to the left 
of the decimal point and pads with spaces to the left of the zero. 


If there are more reserved positions to the right of the decimal point 
than fractional digits, VAX BASIC prints trailing zeros in those posi- 
tions. 


If there are fewer reserved positions to the right of the decimal 
point than fractional digits, VAX BASIC rounds the number to fit the 
reserved positions. 


If a number does not fit in the specified format field, VAX BASIC 
prints a percent sign warning symbol (%), followed by the number in 
PRINT format. 


Formatting String Output 


e Format string characters control string output and can be entered 
as either uppercase or lowercase characters. All format characters 
except the backslash and exclamation point must start with 
a single quotation mark (’). A single quote by itself reserves 
one character position. A single quote followed by any format 
characters marks the beginning of a character format field and 
reserves one character position. 


e L reserves one character position. The number of Ls plus the 
leading single quote determines the field’s size. VAX BASIC left- 
justifies the print expression and pads with spaces if the print 
expression is less than or equal to the field’s width. If the print 
expression is larger than the field, VAX BASIC left-justifies the 
expression and truncates its right side to fit the field. 


eR reserves one character position. The number of Rs plus the 
leading single quote determines the field’s size. VAX BASIC right- 
justifies the print expression and pads with spaces if the print 
expression is less than or equal to the field’s width. If the print 
expression is larger than the field, VAX BASIC truncates the right 
side to fit the field. 
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C reserves one character position. The number of Cs plus the 
leading single quote determines the field’s size. If the string does 
not fit in the field, VAX BASIC truncates its right side. Otherwise, 
VAX BASIC centers the print expression in this field. If the string 
cannot be centered exactly, it is offset one character to the left. 


E reserves one character position. The number of Es plus the 
leading single quote determines the field’s size. VAX BASIC left- 
justifies the print expression if it is less than or equal to the field’s 
width and pads with spaces. Otherwise, VAX BASIC expands the 
field to hold the entire print expression. 


Two backslashes (\ \) when separated by n spaces reserve n+2 
character positions. PRINT USING left-justifies the string in this 
field. VAX BASIC does not allow a leading quotation mark with 
this format. 


An exclamation point (!) creates a 1-character field. The excla- 
mation point both starts and ends the field. VAX BASIC does not 
allow a leading quotation mark with this format. 


15. VAX BASIC interprets any other characters in the format string as 
string literals and prints them exactly as they appear. 


16. If a COMMA or semicolon follows the last item in output-list 


When printing to a terminal, VAX BASIC does not generate a 
line terminator after printing the last item. The next item printed 
with a PRINT statement is printed at the position specified by 
the separator character following the last item in the first PRINT 
statement. 


When printing to a terminal-format file, VAX BASIC does not 
write out the record until a PRINT statement without trailing 
punctuation executes. 


17. If no punctuation follows the last item in output-list: 


When printing to a terminal, VAX BASIC generates a line termina- 
tor after printing the last item. 


When printing to a terminal-format file, VAX BASIC writes out the 
record after printing the last item. 
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Example 1 

PRINT USING “###.###" , -12.345 
PRINT USING "##.###" 12.345 
‘Output 1 

12.345 

12.345 

Example 2 


INPUT "Your Name"; Winner$ 

Jackpot = 10000.0 
PRINT USING "CONGRATULATIONS, 'EEEEEEEEE, YOU WON $$#####.##", Winner$, Jackpot 
END 


Output 2 


Your Name? Hortense Corabelle 
CONGRATULATIONS, Hortense Corabelle, YOU WON $10000.00 
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The PROD$ function returns a numeric string that is the product of two 
numeric strings. The precision of the returned numeric string depends on 
the value of an integer argument. 


Format 


str-var = PRODS (str-exp1, str-exp2, int-exp) 
Syntax Rules 


1. Str-exp1 and str-exp2 specify the numeric strings you want to multiply. 
A numeric string can have one of the following formats: 
e An optional minus sign (-), ASCII digits, and an optional decimal 
point (.) 
e An optional minus sign, ASCII digits, an optional decimal point, 
the letter E, an optional minus sign, and a 2-digit exponent 


2. If str-exp consists of more than 60 characters, VAX BASIC signals the 
error “Illegal number” (ERR=52). 


3. Int-exp specifies the numeric precision of str-exp. Table 4-5 shows 
examples of rounding and truncation and the values of int-exp that 
produce them. 
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PRODS 


Str-exp is rounded or truncated, or both, according to the value of 
int-exp. 
If int-exp is between —60 and 60, rounding and truncation occur as 
follows: 


© For positive integer expressions, rounding occurs to the right of 


the decimal place. For example, if int-exp is 1, rounding occurs 
one digit to the right of the decimal place (the number is rounded 
to the nearest tenth). If int-exp is 2, rounding occurs two digits 
to the right of the decimal place ‘(the number is rounded to the 
nearest hundredth), and so on. 


e If int-exp is zero, VAX BASIC rounds to the nearest unit. 


e For negative integer expressions, rounding occurs to the left of the 
decimal point. If int-exp is -1, for example, VAX BASIC moves the 
decimal point one place to the left, then rounds to units. If int-exp 
is -2, rounding occurs two places to the left of the decimal point; 
VAX BASIC moves the decimal point two places to the left, then 
rounds to tens. 


If int-exp is between 9940 and 10,060, truncation occurs as follows: 


e If int-exp is 10,000, VAX BASIC truncates the number at the 
decimal point. 


e If int-exp is greater than 10,000 (10000 plus n) VAX BASIC 
truncates the numeric string n places to the right of the decimal 
point. For example, if int-exp is 10,001 (10,000 plus 1), VAX 
BASIC truncates the number starting one place to the right of the 
decimal point. If int-exp is 10,002 (10,000 plus 2), VAX BASIC 
truncates the number starting two places to the right of the 
decimal point, and so on. 


e If int-exp is less than 10,000 (10,000 minus n), VAX BASIC trun- 
cates the numeric string n places to the left of the decimal point. 
For example, if int-exp is 9999 (10,000 minus 1), VAX BASIC 
truncates the number starting one place to the left of the decimal 
point. If 9998 (10,000 minus 2), VAX BASIC truncates starting two 
places to the left of the decimal point, and so on. 
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4. If int-exp is not between —60 and 60 or 9940 and 10,060, VAX BASIC 
returns a value of zero. 


5. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 


Example 


DECLARE STRING num_expi, & 
num_exp2, & 
product 
num_exp1 = "34.555" 
num_exp2 = "297.676" 
product = PROD$(num_exp1, num_exp2, 1) 
PRINT product 


Output 
10286 .2 
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The PROGRAM statement allows you to identify a main program with a 
name other than the file name. 


Format 


PROGRAM _prog-name 
Syntax Rules 


1. Prog-name specifies the module name of the compiled source and 
cannot be the same as any SUB, FUNCTION or PICTURE name. 

2. Prog-name also defines the global entry point name for the main 
program. 

3. The first character of a prog-name must be an alphabetic character 
(A through Z). The remaining characters, if any, can be any combi- 
nation of alphabetic characters, digits (0 through 9), dollar signs ($), 
periods (.), and underscores (_). 


4. Prog-name cannot be a quoted name. 
Remarks 


1. The PROGRAM statement must be the first statement in a main 
program and can be preceded only by comment fields and lexical 
directives. 

2. If you insert the program into a text or object library or examine it 
using the VAX/VMS Debugger, the program name you specify will be 
the module name used. 

3. The PROGRAM statement is optional; VAX BASIC allows you to 
specify an END PROGRAM statement and an EXIT PROGRAM 
statement without a matching PROGRAM statement. 
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Example 
PROGRAM first_test 


END PROGRAM 
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PUT 


The PUT statement transfers data from the record buffer to a file. PUT 
statements are valid on RMS sequential, relative, and indexed files. You 
cannot use PUT statements on terminal-format files or virtual array files. 


Format 


PUT #chnl-exp [, RECORD num-exp [ , COUNT int-exp ] ] 


Syntax Rules 


Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 

The RECORD clause allows you to randomly write records to a rela- 
tive or sequential fixed file by specifying the record number. 

Num-exp must be between 1 and the maximum record number al- 
lowed for the file. VAX BASIC does not allow you to use the RECORD 
clause on sequential variable, sequential stream, or indexed files. 


Int-exp in the COUNT clause specifies the record’s size. If there is 
no COUNT clause, the record’s size is that defined by the MAP or 
RECORDSIZE clause in the OPEN statement. The RECORDSIZE 
clause overrides the MAP clause. 


e If you write a record to a file with variable-length records, int-exp 
must be between zero and the maximum record size specified in 
the OPEN statement. 


e If you write a record to a file with fixed-length records, the 
COUNT clause serves no purpose. If used, int-exp must equal the 
record size specified in the OPEN statement. 
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Remarks 


For sequential access, the file associated with chnl-exp must be open 
with ACCESS WRITE, MODIFY, SCRATCH, or APPEND. 


To add records to an existing sequential file, open it with ACCESS 
APPEND. If you are not at the end of the file when attempting a PUT 
to a sequential file, VAX BASIC signals “Not at end of file’ (ERR=149). 


After a PUT statement executes, there is no current record pointer. 
The next record pointer is set as follows: 


¢ For sequential files, variable and stream PUT operations set the 
next record pointer to the end of the file. 


e For relative files, a sequential PUT operation sets the next record 
pointer to the next record plus 1. 


e For relative and sequential fixed files, a random PUT operation 
leaves the next record pointer unchanged. 


e For indexed files, a PUT operation leaves the next record pointer 
unchanged. 


When you specify a RECORD clause, VAX BASIC evaluates num-exp 
and uses this value as the relative record number of the target cell. 


e If the target cell is empty or occupied by a deleted record, VAX 
BASIC places the record in that cell. 


e If there is a record in the target cell and the file has not been 
opened as a VIRTUAL file, the PUT statement fails, and VAX 
BASIC signals the error “Record already exists” (ERR=153). 


A PUT statement with no RECORD clause writes records to the file as 
follows: 


e For sequential variable and stream files, a PUT operation adds a 
record at the end of the file. 


e For relative and sequential fixed files, a PUT operation places the 
record in the empty cell pointed to by the next record pointer. If 
the file is empty, the first PUT operation places a record in cell 
number 1, the second in cell number 2, and so on. 


e For indexed files, RMS stores records in order of ascending pri- 
mary key value and updates all indexes so that they point to the 
record. 
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6. When you a open file as ORGANIZATION VIRTUAL, the file you 
open is a sequential fixed file with a record size that is a multiple of 
512 bytes. You can then access the file with the FIND, GET, PUT, 
or UPDATE statements or through one or more virtual arrays. VAX 
BASIC allows you to overwrite existing records in a file not containing 
virtual arrays and opened as ORGANIZATION VIRTUAL by using 
the PUT statement with a RECORD clause. All other organizations 
require the UPDATE statement to change an existing record. DIGITAL 
recommends that you also use the UPDATE statement to change 
existing records in VIRTUAL files that do not contain virtual arrays. 


7. If an existing record in an indexed file has a record with the same 
key value as the one you want to put in the file, VAX BASIC signals 
the error “Duplicate key detected” (ERR=134) if you did not specify 
DUPLICATES for the key in the OPEN statement. If you specified 
DUPLICATES, RMS stores the duplicate records in a first-in/first-out 
sequence. 

8. The number specified in the COUNT clause determines how many 
bytes are transferred from the buffer to a file: 


e If you have not completely filled the record buffer before executing 
a PUT statement, VAX BASIC pads the record with nulls to equal 
the specified value. 


e If the specified COUNT value is less than the buffer size, the 
record is truncated to equal the specified value. 


e The number in the COUNT clause must not exceed the size spec- 
ified in the MAP or RECORDSIZE clause in the OPEN statement 
or VAX BASIC signals “Size of record invalid” (ERR=156). 


e For files with fixed length records, the number in the COUNT 
clause must match the record size. 


Example 1 


!Sequential, Relative, Indexed, and Virtual Files 
PUT #3, COUNT 55% 


Example 2 


{Relative and Virtual Files Only 
PUT #5, RECORD 133, COUNT 16% 
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The QUO$ function returns a numeric string that is the quotient of two 
numeric strings. The precision of the returned numeric string depends on 
the value of an integer argument. 


Format 


str-var = QUOS$ (str-exp1, str-exp2, int-exp) 


Syntax Rules 


Remarks 


Str-exp1 and str-exp2 specify the numeric strings you want to divide. 
A numeric string can have one of the following formats: 


e An optional minus sign (—), ASCII digits, and an optional decimal 
point (.) 

e An optional minus sign, ASCII digits, an optional decimal point, 
the letter E, an optional minus sign, and a 2-digit exponent 


Int-exp specifies the numeric precision of str-exp. Table 4-5 shows 
examples of rounding and truncation and the values of int-exp that 
produce them. 


If str-exp consists of more than 60 characters, VAX BASIC signals the 
error “Illegal number” (ERR=52). 


Str-exp is rounded or truncated, or both, according to the value of 
int-exp. 
If int-exp is between -60 and 60, rounding and truncation occur as 
follows: 


e For positive integer expressions, rounding occurs to the right of 
the decimal place. For example, if int-exp is 1, rounding occurs 
one digit to the right of the decimal place (the number is rounded 
to the nearest tenth). If int-exp is 2, rounding occurs two digits 
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to the right of the decimal place (the number is rounded to the 
nearest hundredth), and so on. 


If int-exp is zero, VAX BASIC rounds to the nearest unit. 


For negative integer expressions, rounding occurs to the left of the 
decimal point. If int-exp is -1, for example, VAX BASIC moves the 
decimal point one place to the left, then rounds to units. If int-exp 
is -2, rounding occurs two places to the left of the decimal point; 
VAX BASIC moves the decimal point two places to the left, then 
rounds to tens. 


If int-exp is between 9940 and 10,060, truncation occurs as follows: 


If int-exp is 10000, VAX BASIC truncates the number at the 
decimal point. 


If int-exp is greater than 10,000 (10,000 plus n) VAX BASIC 
truncates the numeric string 1 places to the right of the decimal 
point. For example, if int-exp is 10,001 (10,000 plus 1), VAX 
BASIC truncates the number starting one place to the right of the 
decimal point. If int-exp is 10,002 (10,000 plus 2), VAX BASIC 
truncates the number starting two places to the right of the 
decimal point, and so on. 


If int-exp is less than 10,000 (10,000 minus n), VAX BASIC trun- 
cates the numeric string n places to the left of the decimal point. 
For example, if int-exp is 9999 (10,000 minus 1), VAX BASIC 
truncates the number starting one place to the left of the decimal 
point. If 9998 (10,000 minus 2), VAX BASIC truncates starting two 
places to the left of the decimal point, and so on. 


If int-exp is not between —60 and 60 or 9940 and 10,060, VAX BASIC 
returns a value of zero. 


If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to an integer of the default size. 
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DECLARE STRING num_stri, & 
num_str2, & 


quotient 
num_stri = "458996.43" 
num_str2 = "123222.444" 
quotient = QU0$(num_stri, num_str2, 2) 


PRINT quotient 


Output 
3.72 


4-294 Statements and Functions 


RADS 


RADS 


The RAD$ function converts a specified integer in Radix-50 format to a 
3-character string. 


NOTE 


The RAD$ function is supported only for compatibility with 
BASIC-PLUS-2. DIGITAL recommends that you do not use the 
RAD$ function for new program development. 


Format 


str-var = RAD$ (int-var) 
Syntax Rules 
None. 
Remarks 


1. The RAD$ function converts int-var to a 3-character string in Radix-50 
format and stores it in str-var. Radix-50 format allows you to store 
three characters of data as a 2-byte integer. 

2. VAX BASIC supports the RAD$ function, but not its complement, the 
FSS$ function. 

3. If you specify a floating-point variable for int-var, VAX BASIC trun- 
cates it to an integer of the default size. 
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Example 


DECLARE STRING radix 
radix = RAD$(999) 
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RANDOMIZE 


The RANDOMIZE statement gives the random number function, RND, a 
new starting value. 


Format 


{ RANoOM. 


Syntax Rules 
None. 
Remarks 


1. Without the RANDOMIZE statement, successive runs of the same 
program generate the same random number sequence. 


2. If you use the RANDOMIZE statement before invoking the RND 
function, the starting point changes for each run. Therefore, a different 
random number sequence appears each time. 


DECLARE REAL random_num 
RANDOMIZE 
FOR I = 1 TO 2 
random_num = RND 
PRINT random_num 
NEXT I 
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Output 


. 379784 
. 311572 
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The RCTRLC function disables CTRL/C trapping. 


Format 
int-var = RCTRLC 


Syntax Rules 
None. 
Remarks 


1. After VAX BASIC executes the RCTRLC function, a CTRL/C typed 
at the terminal returns you to DCL command level or to the BASIC 
environment. 


2. RCTRLC always returns a value of zero. 


Y = RCTRLC 
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The RCTRLO function cancels the effect of a CTRL/O typed on a specified 
channel. 


Format 
int-var = RCTRLO (chnl-exp) 


Syntax Rules 


Chnl-exp must refer to a terminal. 


Remarks 
1. If you type a CTRL/O to cancel terminal output, nothing is printed 
on the specified terminal until your program executes the RCTRLO 
or until you type another CTRL/O, at which time normal terminal 
output resumes. 
2. The RCTRLO function always returns a value of zero. 
3. RCTRLO has no effect if the specified channel is open to a device that 
does not use the CTRL/O convention. 
Example 


PRINT "A" FOR I% = 1% TO 10% 
Y%4 = RCTRLO(O%) 
PRINT "Normal output is resumed" 
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> > > 


Output off 


Normal output is resumed 


RCTRLO 
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READ 


The READ statement assigns values from a DATA statement to variables. 


Format 
READ var,... 


Syntax Rules 


Var cannot be a DEF function name, unless the READ statement is inside 
the multi-line DEF body. 


Remarks 


1. If your program has a READ statement without DATA statements, 
VAX BASIC signals a compile-time error. 


2. When VAX BASIC initializes a program unit, it forms a data sequence 
of all values in all DATA statements. An internal pointer points to the 
first value in the sequence. 


3. When VAX BASIC executes a READ statement, it sequentially assigns 
values from the data sequence to variables in the READ statement 
variable list. As VAX BASIC assigns each value, it advances the 
internal pointer to the next value. 


4. VAX BASIC signals the error “Out of data” (ERR=57) if there are fewer 
data elements than READ statements. Extra data elements are ignored. 


5. The data type of the value must agree with the data type of the 
variable to which it is assigned or VAX BASIC signals “Data format 
error” (ERR=50). 

6. If you read a string variable, and the DATA element is an unquoted 
string, VAX BASIC ignores leading and trailing spaces. If the DATA 
element contains any commas, they must be inside quotation marks. 
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READ 


VAX BASIC evaluates subscript expressions in the variable list after it 
assigns a value to the preceding variable, and before it assigns a value 
to the subscripted variable. For instance, in the following example, 
VAX BASIC assigns the value of 10 to variable A, then assigns the 
string, LESTER, to array element A$(A). 


READ A, A$(10) 


DATA 10, LESTER 


The string, LESTER, will be assigned to A$(10). 


DECLARE STRING A,B,C 
READ A,B,C 

DATA "X", "y", "z 
PRINT A+B+C 


Output 


XYZ 
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The REAL function converts a numeric expression or numeric string to a 
specified or default floating-point data type. 


Format 
, SINGLE 
ee, , DOUBLE 
real-var = REAL (exp ' GFLOAT ) 
, HFLOAT 


Syntax Rules 


Exp can be either numeric or string. If a string, it can contain the ASCII 
digits 0 through 9, uppercase E, a plus sign (+), a minus sign (—), and a 
period (.). 


Remarks 


1. VAX BASIC evaluates exp, then converts it to the specified REAL size. 
If you do not specify a size, VAX BASIC uses the default REAL size. 


2. VAX BASIC ignores leading and trailing spaces and tabs if exp is a 
string. 


3. The REAL function returns a value of zero when a string argument 
contains only spaces and tabs, or when the argument is null. 
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DECLARE STRING any_num 
INPUT “Enter a number"; any_num 
PRINT REAL(any_num, DOUBLE) 


Output 


Enter a number? 123095959 
. 123096E+09 
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RECORD 
The RECORD statement lets you name and define data structures in a 
VAX BASIC program and provides the VAX BASIC interface to the VAX 
Common Data Dictionary (CDD). You can use the defined RECORD name 
anywhere a VAX BASIC data type keyword is valid if all data types are 
valid in that context. 

Format 


RECORD _rec-name 
rec-component 


END RECORD / rec-name ] 


data-type rec-item [ ,... ] 
rec-component: group-clause 
variant-clause 


rec-item: array { [ int-const! TO J int-const2 ,...) [ = int-const ] 


| unsubs-var [ = int-const ] 
FILL / ( int-const ) ] [ = int-const ] 


group-clause: GROUP group-name { [ int-const1 TO J int-const2,... ) ] 
rec-component 


END GROUP [ group-name | 


4-306 Statements and Functions 


RECORD 


variant-clause: VARIANT 


case-clause: 


Syntax Rules 


case-clause 


END VARIANT 


CASE 
[ rec-component ] 


Each line of text in a RECORD, GROUP, or VARIANT block can have 
an optional line number. 


Data-type can be a VAX BASIC data type keyword or a previously 
defined RECORD name. Table 1-2 lists and describes VAX BASIC 
data type keywords. 

If the data type of a rec-item is STRING, the string is fixed-length. 
You can supply an optional string length with the = int-const clause. If 
you do not specify a string length, the default is 16. 

When you create an array of components with GROUP or create an 
array as a rec-item, VAX BASIC allows you to specify both lower 

and upper bounds. The upper bound is required; the lower bound is 
optional. 


e Int-const1 specifies the lower bounds of the array. 


¢ Int-const2 specifies the upper bounds of the array and when 
accompanied by int-const1, must be preceded by the keyword TO. 


e Int-const1 must be less than or equal to int-const2. 


¢ If you do not specify int-const1, VAX BASIC uses zero as the 
default lower bound. 
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Remarks 


The total size of a RECORD cannot exceed 65,535 bytes. 


The declarations between the RECORD statement and the END 
RECORD statement are called a RECORD block. 


Variables and arrays in a RECORD definition are also called RECORD 
components. 


The RECORD statement names and defines a data structure called 
a RECORD template, but does not allocate any storage. When you 
use the RECORD template as a data type in a statement such as 
DECLARE, MAP, or COMMON, you declare a RECORD instance. 
This declaration of the RECORD instance allocates storage for the 
RECORD. For example: 


DECLARE EMPLOYEE emp_rec 


This statement declares a variable named emp_rec, which is an 
instance of the user-defined data type EMPLOYEE. 


Rec-item 


e The rec-name qualifies the group-name and the group-name qualifies 
the rec-item. You can access a particular rec-item within a record 
by specifying rec-name::group-name::rec-item. This specification 
is called a fully qualified reference. The full qualification of a 
rec-item is also called a component path name. 


¢ Rec-item must conform to the rules for naming VAX BASIC 
variables. 


¢ Whenever you access an elementary record component, that is, a 
variable named in a RECORD definition, you do it in the context 
of the record instance. Therefore, rec-item names need not be 
unique in your program. For example, you can have a variable 
called first_name in any number of different RECORD definitions. 
However, you cannot use a VAX BASIC reserved keyword as a 
rec-item name and you cannot have two variables or arrays with 
the same name at the same level in the RECORD or GROUP 
definition. 

¢ The group-name is optional in a rec-item specification unless there 
is more than one rec-item with the same name or the group-name 
has subscripts. For example: 
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DECLARE EMPLOYEE Emp_rec 


RECORD Address 
STRING Street, City, State, Zip 
END RECORD Address 
RECORD Employee 
GROUP Emp_name 
STRING First = 15 
STRING Middle = 1 
STRING Last = 15 
END GROUP Emp_name 
ADDRESS Work 
ADDRESS Home 
END RECORD Employee 


You can access the rec-item “Last” by specifying only “Emp_ 
rec::Last” because only one rec-item is named “Last”. However, 
if you try to reference “Emp_rec::City”, VAX BASIC signals an 
error because “City” is an ambiguous field, a component of both 
“Work” and “Home”. To access “City”, you must specify either 
“Emp_trec::Work::City” or “Emp_rec::Home::City”. 


Group-clause 


The declarations between the GROUP keyword and the END 
GROUP keywords are called a GROUP block. The GROUP 
keyword is valid only within a RECORD block. 


A subscripted group is similar to an array within the record. The 
group can have both lower and upper bounds for one or more 
dimensions. Each group element consists of all the record items 
contained within the including other groups. 


Variant-clause 


The declarations between the VARIANT keyword and the END 
VARIANT keywords are called a VARIANT block. 


The amount of space allocated for a VARIANT field in a RECORD 
is equal to the space needed for the variant field requiring the 
most storage. 

A variant defines the record items that overlay other items, 
allowing you to redefine the same storage one or more ways. 


Case-clause 


Each case in a variant starts at the position in the record where 
the variant begins. 


The size of a variant is the size of the longest case in that variant. 
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1000 RECORD Employee 


GROUP Emp_name 
STRING Last = 15 
STRING First = 14 
STRING Middle = 1 
END GROUP Emp_name 
GROUP Emp_address 
STRING Street = 15 
STRING City = 20 
STRING State = 2 
DECIMAL(5,0) Zip 
END GROUP Emp_address 
STRING Wage_class = 2 
VARIANT 
CASE 
GROUP Hourly 
DECIMAL(4,2) Hourly_wage 
SINGLE Regular_pay_ytd 
SINGLE Overtime_pay_ytd 
END GROUP Hourly 
CASE 
GROUP Salaried 
DECIMAL(7,2) Yearly_salary 
SINGLE Pay_ytd 
END GROUP Salaried 
CASE 
GROUP Executive 
DECIMAL(8,2) Yearly_salary 
SINGLE Pay_ytd 
SINGLE Expenses_ytd 
END GROUP Executive 
END VARIANT 


END RECORD Employee 
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RECOUNT 


The RECOUNT function returns the number of characters transferred by 
the last input operation. 


Format 
int-var = RECOUNT 


Syntax Rules 
None. 
Remarks 


1. The RECOUNT value is reset by every input operation on any chan- 
nel, including channel #0. 


e After an input operation from your terminal, RECOUNT contains 
the number of characters (bytes), including line terminators, 
transferred. 


e After accessing a file record, RECOUNT contains the number of 
characters in the record. 


2. Because RECOUNT is reset by every input operation on any channel, 
you should copy the RECOUNT value to a different storage location 
before executing another input operation. 


3. If an error occurs during an input operation, the value of RECOUNT 
is undefined. 


4. RECOUNT is unreliable after a CTRL/C interrupt because the 
CTRL/C trap may have occurred before VAX BASIC set the value 
for RECOUNT. 


5. The RECOUNT function returns a LONG value. 
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DECLARE INTEGER character_count 

INPUT "Enter a sequence of numeric characters"; character_count 
character_count = RECOUNT 

PRINT character_count; "characters received (including CR and LF)" 


Output 


Enter a sequence of numeric characters? 12345678 
10 characters received (including CR and LF) 
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The REM statement allows you to document your program. 


Format 
REM = [comment] 


Syntax Rules 


1. REM must be the only statement on the line or the last statement on a 
multi-statement line. 


2. WAX BASIC interprets every character between the keyword REM and 
the next line number as part of the comment. 


3. VAX BASIC does not allow you to specify the REM statement in 
programs that do not contain line numbers. 


Remarks 


1. Because the REM statement is not executable, you can place it any- 
where in a program, except where other statements, such as SUB and 
END SUB, must be the first or last statement in a program unit. 


2. When the REM statement is the first statement on a line-numbered 
line, VAX BASIC treats any reference to that line number as a refer- 
ence to the next higher-numbered executable statement. 


3. The REM statement is similar to the comment field that begins with 
an exclamation point, with one exception: the REM statement must be 
the last statement on a BASIC line. The exclamation point comment 
field can be ended with another exclamation point or a line terminator 
and followed by a VAX BASIC statement. See Chapter 1 of this 
manual for more information on the comment field. 
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10 REM This is a multi-line comment 
All text up to BASIC line 20 
is part of this REM statement. 
Any BASIC statements on line 10 
are ignored. PRINT "This does not 
execute". 

20 PRINT "This will execute" 


Output 


This will execute 
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REMAP 


The REMAP statement defines or redefines the position in the storage area 
of variables named in the MAP DYNAMIC statement. 


Format 


REMAP  (map-dyn-name) remap-item.... 


map-dyn-name: 


remap-item: 


map-name \ 
static-str-var 

num-var 

num-array-name { [ int-exp,... ] ) 

str-var [ = int-exp ] 

str-array-name ( [ int-exp,...] )[ = int-exp ] 
[ data-type ] FILL [ ( int-exp) ] [ = int-exp ] 
FILL% /[ ( int-exp ) ] 

FILL$ [ ( int-exp ) J[ = int-exp ] 


Syntax Rules 


1. Map-dyn-name can be either a map name or a static string variable. 


Map-name is the storage area named in a MAP statement. 


If you specify a map name, then a MAP statement with the same 
name must precede both the MAP DYNAMIC statement and the 
REMAP statement. 


When you specify a static string variable, the string must be 
declared before you can specify a MAP DYNAMIC statement or a 
REMAP statement. 


If you specify a static-str-var, the following restrictions apply: 
— Static-str-var cannot be a string constant. 
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— Static-str-var cannot be the same as any previously declared 
map-item in a MAP DYNAMIC statement. 


— If static-str-var is a parameter to the subprogram containing 
the REMAP statement, static-str-var cannot be a RECORD 
component. 


— Static-str-var cannot be a subscripted variable. 


— Static-str-var cannot be a parameter declared in a DEF or DEF* 
function. 


2. Remap-item names a variable, array, or array element declared in a 
preceding MAP DYNAMIC statement: 


¢ Num-var specifies a numeric variable or array element. Num- 
array-name followed by a set of empty parentheses specifies an 
entire numeric array. 


e Str-var specifies a string variable or array element. Str-array-name 
followed by a set of empty parentheses, specifies an entire fixed- 
length string array. You can specify the number of bytes to be 
reserved for string variables and array elements with the =int-exp 
clause. The default string length is 16. 


3. Remap-item can also be a FILL item. The FILL, FILL%, and FILL$ 
keywords let you reserve parts of the record buffer. Int-exp specifies 
the number of FILL items to be reserved. The =int-exp clause allows 
you to specify the number of bytes to be reserved for string FILL 
items. Table 4-2 describes FILL item format and storage allocation. 


NOTE 


In the FILL clause, (int-exp) represents a repeat count, not 
an array subscript. FILL (1), for example, represents 1 
elements, not n + 1. 


4. All remap-items, except FILL items, must have been named in a 
previous MAP DYNAMIC statement, or VAX BASIC signals an error. 


5. Data-type can be any VAX BASIC data type keyword or a data type 
defined in a RECORD statement. Data type keywords and their size, 
range, and precision are listed in Table 1-2 in this manual. You can 
specify a data type only for FILL items. 


e When you specify a data type before a FILL keyword in a REMAP 
statement, the FILL item is of that data type. The specified data 
type applies only to that one FILL item. 


e If you do not specify any data type for a FILL item, the FILL item 
takes the current default data type and size. 
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6. Remap-items must be separated with commas. 
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Remarks 


REMAP 


The REMAP statement does not affect the amount of storage allocated 
to the map area. 


Each time a REMAP statement executes, VAX BASIC sets record 
pointers to the named map area for the specified variables from left to 
right. 

The REMAP statement must be preceded by a MAP DYNAMIC state- 
ment or VAX BASIC signals the error “No such MAP area <name> ”. 
The MAP statement or static string variable creates a named area of 
static storage, the MAP DYNAMIC statement specifies the variables 
whose positions can change at runtime, and the REMAP statement 
specifies the new positions for the variables named in the MAP 
DYNAMIC statement. 


Before you can specify a map name in a REMAP statement, there 
must be a MAP statement in the program unit with the same map 
name. Otherwise, VAX BASIC signals the error “ <Name> is not a 
DYNAMIC MAP variable of MAP <name> ”. Similarly, before you 
can specify a static string variable in a REMAP statement, the string 
variable must be declared. Otherwise, VAX BASIC signals the same 
error message. 


If a static string variable is the same as a map name, VAX BASIC 
overrides the static string name and uses the map name. 


Until the REMAP statement executes, all variables named in the MAP 
DYNAMIC statement point to the first byte of the MAP area and all 
string variables have a length of zero. When the REMAP statement 
executes, VAX BASIC sets the internal pointers as specified in the 
REMAP statement. For example: 


100 MAP (DUMMY) STRING map_buffer = 50 
MAP DYNAMIC (DUMMY) LONG A, STRING B, SINGLE C(7) 
REMAP (DUMMY) B=14, A, C() 


The REMAP statement sets a pointer to byte 1 of DUMMY for string 
variable B, a pointer to byte 15 for LONG variable A, and pointers to 
bytes 19, 23, 27, 31, 35, 39, 43, and 47 for the elements in SINGLE 
array C. 
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7. You can use the REMAP statement to redefine the pointer for an array 
element or variable more than once in a single REMAP statement. For 
example: 


100 MAP (DUMMY) STRING FILL = 48 
MAP DYNAMIC (DUMMY) LONG A, B(10) 
REMAP (DUMMY) B(), B(O) 


This REMAP statement sets a pointer to byte 1 in DUMMY for array 
B. Because array B uses a total of 44 bytes, the pointer for the first 
element of array B, B(0) points to byte 45. References to array element 
B(0) will be to bytes 45 through 48. Pointers for array elements 1 
through 10 are set to bytes 5, 9, 13, 17 and so forth. 


8. Because the REMAP statement is local to a program module, it affects 
pointers only in the program module in which it executes. 


Example 1 
DECLARE LONG CONSTANT emp_fixed_info = 4 +9 + 2 


MAP (emp_buffer) LONG badge, & 
STRING social_sec_num = 9, & 
BYTE name_length, & 
address_length, & 
FILL (60) 
MAP DYNAMIC (emp_buffer) STRING emp_name, & 
emp_address 
WHILE 1% 
GET #1 
REMAP (emp_buffer) STRING FILL = emp_fixed_info, & 
emp_name = name_length, & 


emp_address = address_length 
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PRINT emp_name 
PRINT emp_address 


PRINT 
NEXT 

END 
Example 2 


SUB deblock (STRING input_rec, STRING item()) 
MAP DYNAMIC (input_rec) STRING A(1 TO 3) 
REMAP (input_rec) & 


A(1) = 5, & 
A(2) = 3, & 
A(3) = 4 


FOR I = LBOUND(A) TO UBOUND(A) 
item(I) = A(I) 
NEXT I 
END SUB 


REMAP 
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RESET 


The RESET statement is a synonym for the RESTORE statement. See the 
RESTORE statement for more information. 


Format 
RESET [| #chnil-exp [, KEY #int-exp ] ] 
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RESTORE 


The RESTORE statement resets the DATA pointer to the beginning of the 
DATA sequence, or sets the record pointer to the first record in a file. 


Format 


RESTORE /[ #chnl-exp [, KEY #int-exp ] ] 


Syntax Rules 


Remarks 


Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 

Int-exp must be between zero and the number of keys in the file 
minus 1. It must be immediately preceded by a number sign (#). 


If you do not specify a channel, RESTORE resets the DATA pointer to 
the beginning of the DATA sequence. 


RESTORE affects only the current program unit. Thus, executing 
a RESTORE statement in a subprogram does not affect the DATA 
pointer in the main program. 


If there is no channel specified, and the program has no DATA 
statements, RESTORE has no effect. 


The file specified by chnl-exp must be open. 


If chnl-exp specifies a magnetic tape file, VAX BASIC rewinds the tape 
to the first record in the file. 


The KEY clause applies to indexed files only. It sets a new key of 
reference equal to int-exp and sets the next record pointer to the first 
logical record in that key. 
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Example 


7. 


10. 


For indexed files, the RESTORE statement without a KEY clause sets 
the next record pointer to the first logical record specified by the 
current key of reference. If there is no current key of reference, the 
RESTORE statement sets the next record pointer to the first logical 
record of the primary key. 

If you use the RESTORE statement on any file type other than in- 
dexed, VAX BASIC sets the next record pointer to the first record in 
the file. 

The RESTORE statement is not allowed on virtual array files or on 
files opened on unit record devices. 


For information on the RESTORE GRAPHICS statement, see 
Programming with VAX BASIC Graphics. 


RESTORE #7%, KEY #4% 
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The RESUME statement marks an exit point from an ON ERROR error- 
handling routine. VAX BASIC clears the error condition and returns 
program control to a specified line number, label or to the program block 
in which the error occurred. 


NOTE 


The RESUME statement is supported for compatibility with 
other DIGITAL BASICs. For new program development, 
DIGITAL recommends that you use WHEN blocks. 


Format 
RESUME / target ] 


Syntax Rules 


Target must be a valid VAX BASIC line number or label and must exist in 
the same program unit. 


Remarks 


1. The following restrictions apply: 


e¢ The RESUME statement cannot appear within a protected region, 
or within an attached or detached handler. 


e The target of a RESUME statement cannot exist within a protected 
region or handler. 


e The RESUME statement cannot be used in a multi-line DEF unless 
the target is also in the DEF function definition. 


e¢ The execution of a RESUME with no target is illegal if there is no 
error active. 
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e A RESUME statement cannot transfer control out of the current 
program unit. Therefore, a RESUME statement with no target 
cannot terminate an error handler if the error handler is handling 
an error that occurred in a subprogram or an external function, 
and the error was passed to the calling program’s error handler by 
an ON ERROR GO BACK statement or by default. 


When no target is specified in a RESUME statement, VAX BASIC 
transfers control based on where the error occurs. If the error occurs 
on a numbered line containing a single statement, VAX BASIC always 
transfers control to that statement. When the error occurs within a 
multi-statement line under the following conditions, VAX BASIC acts 
as follows: 


e Within a FOR, WHILE, or UNTIL loop, VAX BASIC transfers 
control to the first statement that follows the FOR, WHILE, or 
UNTIL statement. 


e Within a SELECT block, VAX BASIC transfers control to the start 
of the CASE block in which the error occurs. 


e After a loop or SELECT block, VAX BASIC transfers control to the 
statement that follows the NEXT or END SELECT statement. 


e If none of the above conditions occurs, VAX BASIC transfers 
control back to the statement that follows the most recent line 
number. 


A RESUME statement with a specified line number transfers control 
to the first statement of a multi-statement line, regardless of which 
statement caused the error. 


A RESUME statement with a specified label transfers control to the 
block of code indicated by that label. 


Error_routine: 
IF ERR = 11 
THEN 


ELSE 


END 


CLOSE #1 
RESUME end_of_prog 


RESUME 
IF 


end_of_prog: END 
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RETRY 


The RETRY statement clears an error condition and reexecutes the state- 
ment that caused the error inside a protected region of a WHEN block. 


Format 
RETRY 
Syntax Rules 
The RETRY statement must appear lexically inside of a handler associated 
with a WHEN block. 
Remarks 


The following rules apply to errors that occur during execution of loop 
control statements (not the statements inside the loop body): 


e In FOR...NEXT loops, the RETRY statement reexecutes the FOR 
statement if the error occurs while VAX BASIC is evaluating the limit 
or increment values. 

e¢ In FOR...NEXT loops, if the error occurs while VAX BASIC is evalu- 
ating the index variable, the RETRY statement reexecutes the NEXT 
statement. 

e Ina FOR...UNTIL or FOR...WHILE loop, if an error occurs while VAX 
BASIC is evaluating the relational expression, the RETRY statement 
reexecutes the NEXT statement. 
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10 DECLARE LONG YOUR_AGE 
WHEN ERROR IN 
INPUT "Enter your age"; your_age 
USE 
IF ERR = 50 
THEN RETRY 
ELSE EXIT HANDLER 
END IF 
END WHEN 


4-326 Statements and Functions 


RETURN 


RETURN 


The RETURN statement transfers control to the statement immediately 
following the most recently executed GOSUB or ON...GOSUB statement 
in the current program unit. 


Format 
RETURN 
Syntax Rules 
None. 
Remarks 
1. Once the RETURN is executed in a subroutine, no other statements 
in the subroutine are executed, even if they appear after the RETURN 
statement. 
2. Execution of a RETURN statement before the execution of a GOSUB 
or ON...GOSUB causes VAX BASIC to signal “RETURN without 
GOSUB’ (ERR=72). 
Example 


GOSUB subroutine_1 
subroutine_1: 
RETURN 
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RIGHTS 


The RIGHT$ function extracts a substring from a string’s right side, 
leaving the string unchanged. 


Format 


str-var = RIGHT[$] (str-exp, int-exp) 
Syntax Rules 
None. 
Remarks 


1. The RIGHT$ function extracts a substring from str-exp and stores the 
substring in str-var. The substring begins with the character in the 
position specified by int-exp and ends with the rightmost character in 
the string. 

2. If int-exp is less than or equal to zero, RIGHT$ returns the entire 
string. 

3. If int-exp is greater than the length of str-exp, RIGHT$ returns a null 
string. 

4. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to a LONG integer. 
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Example 


DECLARE STRING main_str, & 
end_result 

main_str = "1234567" 

end_result = RIGHT$(main_str, 3) 

PRINT end_result 


Output 
34567 


RIGHTS 
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The RMSSTATUS function returns the RMS status or the status value of 
the last I/O operation on a specified open I/O channel. 


Format 


long-var = RMSSTATUS ( chnl-exp iy | ) 


Syntax Rules 


1. Chnl-exp must be the number of a channel opened from a VAX BASIC 
routine. 


2. Chnl-exp cannot be zero. 
Remarks 


1. If chnl-exp does not represent an open channel, VAX BASIC signals 
the error “I/O channel not open” (ERR=9). 


2. If you do not specify either STATUS or VALUE, RMSSTATUS returns 
the STATUS value by default. 


3. If you specify STATUS, RMSSTATUS returns the FAB$L_STS or 
the RAB$L_STS status value. However, if you specify VALUE, 
RMSSTATUS returns the FAB$L_STV or the RAB$L_STV status 


value. 
4. Use the RMSSTATUS function to return the status of the following 
operations: 
e RESTORE 
e GET 
e PUT 
e UPDATE 
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e UNLOCK 

e PRINT and PRINT USING 

e INPUT, INPUT LINE, and LINPUT 

e SCRATCH 

e FREE 

e Virtual array references 

To determine the reason for the failure of an OPEN, CLOSE, KILL, or 


NAME...AS statement, use the VMSSTATUS function within an error 
handler. 


Example 1 


“TITLE "RMSSTATUS Example" 
“SBTTL "Reference Manual Examples" 
ZIDENT "V1.0" 


PROGRAM Demo_RMSSTATUS_function 
OPTION CONSTANT TYPE = INTEGER 


OPEN "DOES_NOT_EXIST.LIS" FOR OUTPUT AS 1, & 
SEQUENTIAL VARIABLE, & 
RECORDSIZE 80 


WHEN ERROR IN 
GET #1 
USE 
PRINT "GET Operation failed" 
PRINT "RMS Status ="; RMSSTATUS(1,STATUS) 
PRINT "RMS Status Value ="; RMSSTATUS(1, VALUE) 
END WHEN 


END PROGRAM 


Example 2 


OPTION TYPE=EXPLICIT 
EXTERNAL LONG CONSTANT RMS$_OK_DUP 


MAP (ORDER) LONG ORD_ENTRY, STRING ORD_CUST_NO = 6%, & 
STRING ORD_REMARK = 50% 
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OPEN "ORD_DB" FOR INPUT AS FILE 1%, 
ORGANIZATION INDEXED FIXED, 
MAP ORDER, 
PRIMARY ORD_ENTRY NODUPLICATES, 


& & & & 


ALTERNATE ORD_CUST_NO DUPLICATES 


INPUT "Enter order number"; ORD_ENTRY 
INPUT "Enter customer number" ;ORD_CUST_NO 
INPUT "Remark" ; ORD_REMARK 


! 
! Enter the order. in the order database 

! Check if the customer has other orders 
! 


PUT #1% 
IF RMSSTATUS( 1%, STATUS ) = RMS$_OK_DUP 
THEN 
! 
! The customer has other orders; compute the customer's 
! discount for other orders 
! 
END IF 
CLOSE 1% 
END 


4-332 Statements and Functions 


The RND function returns a random number greater than or equal to zero 
and less than 1. 


Format 
real-var = RND 


Syntax Rules 
None. 
Remarks 


1. If the RND function is preceded by a RANDOMIZE statement, VAX 
BASIC generates a different random number or series of numbers each 
time a program executes. 


2. The RND function returns a pseudorandom number if not preceded 
by a RANDOMIZE statement; that is, each time a program runs, 
VAX BASIC generates the same random number or series of random 
numbers. 


3. The RND function returns a floating-point SINGLE value. 


4. The RND function returns values over a uniform distribution between 
0 and 1. For example, a value between 0 and .1 is as likely as a value 
between .5 and .6. Note the difference between this and a bell-curve 
distribution where the probability of values in the range .3 to .7 is 
higher than the outer ranges. 
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Example 


DECLARE REAL random_num 
RANDOMIZE 
FOR I = 1 TO 3  ‘!FOR loop causes VAX BASIC to print three random numbers 


random_num = RND 
PRINT random_num 


NEXT I 


Output 


.865243 
ATTALT 
. 734673 
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Format 


RSET 


The RSET statement assigns right-justified data to a string variable. RSET 
does not change a string variable’s length. 


RSET _ str-var,... = str-exp 


Syntax Rules 


Remarks 


Str-var cannot be a DEF function name unless the RSET statement is 
inside the DEF function definition. 


1. The RSET statement treats strings as fixed-length. It does not change 
the length of str-var, nor does it create new storage locations. 


2. If str-var is longer than str-exp, RSET right-justifies the data and pads 
it with spaces on the left. 


3. If str-var is shorter than str-exp, RSET truncates str-exp on the left. 


DECLARE STRING test 
test = "ABCDE" 

RSET test = "123" 
PRINT "X" + test 
Output 


X 123 
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SCRATCH 


The SCRATCH statement deletes the current record and all following 
records in a sequential file. 


Format 


SCRATCH #chnl-exp 
Syntax Rules 


Chnl-exp is a numeric expression that specifies a channel associated with a 
file. It must be immediately preceded by a number sign (#). 


Remarks 


1. Before you execute the SCRATCH statement, the file must be opened 
with ACCESS SCRATCH. 


2. The SCRATCH statement applies to ORGANIZATION SEQUENTIAL 
files only. 


3. The SCRATCH statement has no effect on terminals or unit record 
devices. 


4. For disk files, the SCRATCH statement discards the current record and 
all that follows it in the file. The physical length of the file does not 
change. 


5. For magnetic tape files, the SCRATCH statement overwrites the 
current record with two end-of-file marks. 


6. Use of the SCRATCH statement on shared sequential files is not 
recommended. 
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SCRATCH 


SCRATCH #4% 
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The SEG$ function extracts a substring from a main string, leaving the 
original string unchanged. 


Format 


str-var = SEG$ (str-exp, int-exp1, int-exp2) 
SyntaxRules j = ©. | 
None. 
Remarks 


1. VAX BASIC extracts the substring from str-exp, the main string, and 
stores the substring in str-var. The substring begins with the character 
in the position specified by int-exp1 and ends with the character in the 
position specified by int-exp2. 

2. If int-exp1 is less than 1, VAX BASIC assumes a value of 1. 


3. If int-exp1 is greater than int-exp2 or the length of str-exp, the SEG$ 
function returns a null string. 


4. If int-exp1 equals int-exp2, the SEG$ function returns the character at 
the position specified by int-exp1. 


5. Unless int-exp2 is greater than the length of str-exp, the length of the 
returned substring equals int-exp2 minus int-exp1 plus 1. If int-exp2 
is greater than the length of str-exp, the SEG$ function returns all 
characters from the position specified by int-exp1 to the end of str-exp. 


6. If you specify a floating-point expression for int-exp1 or int-exp2, VAX 
BASIC truncates it to LONG integer. 
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DECLARE STRING alpha, center 
alpha = "ABCDEFGHIJK" 

center = SEG$(alpha, 4, 8) 
PRINT center 


Output 
DEFGH 
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SELECT 


The SELECT statement lets you specify an expression, a number of 
possible values the expression may have, and a number of alternative 
statement blocks to be executed for each possible case. 


Format 


SELECT exp] 
case-clause 


[ else-clause ] 
END SELECT 


case-clause: CASEcase-item.... 
[ statement ]... 


ee [rel-op] exp2 \ 
case-item: { exp3 TO exp4 [ ,exp5 TO exp6 J... 


else-clause: CASE ELSE 
[ statement ]... 
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Syntax Rules 


Remarks 


SELECT 


Exp1 is the expression to be tested against the case-clauses and the 
else-clause. It can be numeric or string. 


Case-clause consists of the CASE keyword followed by a case-item and 
statements to be executed when the case-item is true. 


Else-clause consists of the CASE ELSE keywords followed by state- 
ments to be executed when no previous case-item has been selected as 
true. 


Case-item is either an expression to be compared with exp1 or a range 
of values separated with the keyword TO. 


e Rel-op is a relational operator specifying how exp1 is to be com- 
pared to exp2. If you do not include a rel-op, VAX BASIC assumes 
the equals (=) operator. VAX BASIC executes the statements in 
the CASE block when the specified relational expression is true. 


e Exp3 and exp4 specify a range of numeric or string values sepa- 
rated by the keyword TO. Multiple ranges must be separated with 
commas. VAX BASIC executes the statements in the CASE block 
when exp1 falls within any of the specified ranges. 


A SELECT statement can have only one else-clause. The else-clause 

is optional and, when present, must be the last CASE block in the 
SELECT block. 

Each statement in a SELECT block can have its own line number. 

The SELECT statement begins the SELECT BLOCK and the END 
SELECT keywords terminate it. VAX BASIC signals an error if you do 
not include the END SELECT keywords. 


Each CASE keyword establishes a CASE block. The next CASE or 
END SELECT keyword ends the CASE block. 


You can nest SELECT blocks within a CASE or CASE ELSE block. 


VAX BASIC evaluates exp1 when the SELECT statement is first 
encountered; VAX BASIC then compares exp1 with each case-clause in 
order of occurrence until a match is found or until a CASE ELSE block 
or END SELECT is encountered. 
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7. The following conditions constitute a match: 
e Exp] satisfies the relationship to exp2 specified by rel-op. 


e Exp! is greater than or equal to exp3, but less than or equal to 
exp4, greater than or equal to exp5 but less than or equal to exp6, 
and so on. 


8. When a match is found between exp1 and a case-item, VAX BASIC 
executes the statements in the CASE block where the match occurred. 
If ranges overlap, the first match causes VAX BASIC to execute 
the statements in the CASE block. After executing CASE block 
statements, control passes to the statement immediately following the 
END SELECT keywords. 


9. If no CASE match occurs, VAX BASIC executes the statements in 
the else-clause, if present, and then passes control to the statement 
immediately following the END SELECT keywords. 


10. If no CASE match occurs and you do not supply a case-else clause, 
control passes to the statement following the END SELECT keywords. 


100 SELECT A% + BY + Ch 


CASE = 100 

PRINT 'THE VALUE IS EXACTLY 100' 
CASE 1 TO 99 

PRINT 'THE VALUE IS BETWEEN 1 AND 99' 
CASE > 100 

PRINT 'THE VALUE IS GREATER THAN 100' 
CASE ELSE 


PRINT ‘THE VALUE IS LESS THAN 1' 
END SELECT 
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SET PROMPT 


SET PROMPT 


The SET PROMPT statement enables a question mark prompt to appear 
after VAX BASIC executes either an INPUT, LINPUT, INPUT LINE, 
MAT INPUT, or MAT LINPUT statement on channel #0. The SET NO 
PROMPT statement disables the question mark prompt. 


Format 
SET [NO] PROMPT 


Syntax Rules 
None. 
Remarks 


1. If you do not specify a SET PROMPT statement, the default is SET 
PROMPT. 


2. SET NO PROMPT disables VAX BASIC from issuing a question mark 
prompt for the INPUT, LINPUT, INPUT LINE, MAT INPUT, and 
MAT LINPUT statements on channel #0. 


3. Prompting is reenabled when either a SET PROMPT statement or 
a CHAIN statement is executed, or when a NEW, OLD, RUN or 
SCRATCH command is executed in the BASIC environment. 


4. The SET NO PROMPT statement does not affect the string constant 
you specify as the input prompt with the INPUT statement. 
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DECLARE STRING your_name, your_age, your_grade 

INPUT "Enter your name"; your_name 

SET NO PROMPT 

INPUT "Enter your age"; your_age 

SET PROMPT 

INPUT "Enter the last school grade you completed"; your_grade 


Output 


Enter your name? Katherine Kelly 
Enter your age 15 
Enter the last school grade you completed? 9 
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The SGN function determines whether a numeric expression is positive, 
negative, or zero. It returns a 1 if the expression is positive, a -1 if the 
expression is negative, and zero if the expression is zero. 


Format 


int-var = SGN (real-exp) 
Syntax Rules 
None. 
Remarks 


1. If real-exp does not equal zero, SGN returns MAG(real-exp)/real-exp. 
2. If real-exp equals zero, SGN returns a value of zero. 
3. SGN returns a LONG integer. 


DECLARE INTEGER sign 
sign = SGN(46/23) 
PRINT sign 


Output 
1 


Statements and Functions 4-345 


SIN 


The SIN function returns the sine of an angle in radians or degrees. 


Format 


real-var = SIN (real-exp) 
Syntax Rules 


Real-exp is an angle specified in radians or degrees depending upon which 
angle clause you choose with the OPTION statement. 


Remarks 


1. The returned value is between —1 and 1. 


2. VAX BASIC expects the argument of the SIN function to be a real 
expression. When the argument is a real expression, VAX BASIC 
returns a value of the same floating-point size. When the argument is 
not a real expression, VAX BASIC converts the argument to the default 
floating-point size and returns a value of the default floating-point 
size. 


OPTION ANGLE = RADIANS 
DECLARE REAL si_angle 
si_angle = SIN(PI/2) 
PRINT si_angle 


Output 
1 
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SLEEP 


The SLEEP statement suspends program execution for a specified number 
of seconds or until a carriage return is entered from the controlling 
terminal. 


Format 


SLEEP = int-exp 


Syntax Rules 

1. Int-exp is the number of seconds VAX BASIC waits before resuming 
program execution. 

2. Int-exp must be between 0 and 2,147,483,647; if it is greater than 
2,147,483,647, VAX BASIC signals the error “Integer error or overflow” 
(ERR=51). 

Remarks 

1. Pressing the RETURN key on the controlling terminal cancels the 
effect of the SLEEP statement. 

2. All characters typed while SLEEP is in effect, including a RETURN 
character entered to terminate the SLEEP statement, will remain in the 
typeahead buffer. Therefore, if you type RETURN without preceding 
data, an INPUT statement that follows the SLEEP will complete 
without data. 

Example 
SLEEP 120% 
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SPACES 


The SPACE$ function creates a string containing a specified number of 
spaces. 


Format 
str-var = SPACES (int-exp) 


Syntax Rules 


Int-exp specifies the number of spaces in the returned string. 


Remarks 
1. VAX BASIC treats an int-exp less than zero as zero. 
2. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to a LONG integer. 
Example 


DECLARE STRING A, B 
= "41234" 
B = "5678" 
PRINT A + SPACE$(5%) + B 
Output 


1234 5678 
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The SQR function returns the square root of a positive number. 


Format 


real-var -{ Te } (real-exp) 


Syntax Rules 
None. 
Remarks 


1. VAX BASIC signals the error “Imaginary square roots” (ERR=54) when 
real-exp is negative. 


2. VAX BASIC assumes that the argument of the SQR function is a real 
expression. When the argument is a real expression, VAX BASIC 
returns a value of the same floating-point size. When the argument 
is not a real expression, VAX BASIC returns a value of the default 
floating-point size. 


DECLARE REAL root 
root = SQR(20*5) 
PRINT root 


Output 
10 
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STATUS 


The STATUS function returns an integer value containing information 
about the last opened channel. Your program can test each bit to deter- 
mine the status of the channel. 


NOTE 


The STATUS function is supported only for compatibility with 
other DIGITAL BASICs. DIGITAL recommends that you use 
the RMSSTATUS function for new program development. 


Format 


int-var = STATUS 
Syntax Rules 
None. 
Remarks 


1. The STATUS function returns a LONG integer. 


2. The value returned by the STATUS function is undefined until VAX 
BASIC executes an OPEN statement. 


3. The STATUS value is reset by every input operation on any channel. 
Therefore, you should copy the STATUS value to a different storage 
location before your program executes another input operation. 


4. If an error occurs during an input operation, the value of STATUS 
is undefined. When no error occurs, the six low-order bits of the 
returned value contain information about the type of device accessed 
by the last input operation. Table 4-6 lists STATUS bits set by VAX 
BASIC. 
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Table 4-6: VAX BASIC STATUS Bits 
Bit Set Device Type 
Record-oriented device 
Carriage-control device 


Terminal 


0 
1 
2 
3 Directory device 
4 Single directory device 
5 


Sequential block-oriented device (magnetic tape) 


Example 


150 YZ = STATUS 
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STOP 


The STOP statement halts program execution allowing you to optionally 
continue execution. 


Format 
STOP 
Syntax Rules 
None. 
Remarks 


1. The STOP statement cannot appear before a PROGRAM, SUB or 
FUNCTION statement. 


2. The STOP statement does not close files. 


3. When a STOP statement executes in a program executed with the 
RUN command in the BASIC environment, VAX BASIC prints the 
line number and module name associated with the STOP statement, 
then displays the Ready prompt. In response to the prompt, you can 
type immediate mode statements, CONTINUE to resume program 
execution, or any valid compiler command. See the VAX BASIC User 
Manual for more information on immediate mode. 


4. When a STOP statement is in an executable image, the line number, 
module name, and a number sign (#) prompt are printed. In response 
to the prompt, you can type CONTINUE to continue program execu- 
tion or EXIT to end the program. If the program module was compiled 
with the /NOLINE qualifier, no line number is displayed. 
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STOP 


Example 


PROGRAM Stopper 
PRINT "Type CONTINUE when the program stops" 
INPUT "Do you want to stop now"; Quit$ 


IF Quit$ = "yY" 

THEN 
STOP 

ELSE 
PRINT "So what are you waiting for?" 
STOP 

END IF 


PRINT "You told me to continue...thank you" 
END PROGRAM 


Output 


Do you want to stop now? CONTINUE 
So what are you waiting for? 
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STRS 


The STR$ function changes a numeric expression to a numeric character 
string without leading and trailing spaces. 


Format 


str-var = STR$ (num-exp) 
Syntax Rules 
None. 
Remarks 


1. If num-exp is negative, the first character in the returned string is a 
minus sign (-—). 


2. The STR$ function does not return leading or trailing spaces. 


3. When you print a floating-point number that has six decimal digits 
or more but the integer portion has six digits or less (for example, 
1234.567), VAX BASIC rounds the number to six digits (1234.57). If 
a floating-point number’s integer part is seven decimal digits or more, 
VAX BASIC rounds the number to six digits and prints it in E format. 


4, When you print a floating-point number with magnitude between 0.1 
and 1, VAX BASIC rounds it to six digits. When you print a number 
with magnitude smaller than 0.1, VAX BASIC rounds it to six digits 
and prints it in E format. 


5. The STR$ function returns up to 10 digits for LONG integers and up 
to 31 digits for DECIMAL numbers. 


4-354 Statements and Functions 


DECLARE STRING new_num 
new_num = STR$(1543.659) 
PRINT new_num 


Output 
1543.66 
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STRINGS 


STRINGS 


The STRING$ function creates a string containing a specified number of 
identical characters. 


Format 


str-var = STRINGS (int-exp1, int-exp2) 


Syntax Rules 


Remarks 


Int-exp1 specifies the character string’s length. 


Int-exp2 is the decimal ASCII value of the character that makes up the 
string. This value is treated modulo 256. 


VAX BASIC signals the error “String too long” (ERR=227) if int-exp1 is 
greater than 65535. 


If int-exp1 is less than or equal to zero, VAX BASIC treats it as zero. 


VAX BASIC treats int-exp2 as an unsigned 8-bit integer. For example, 
-1 is treated as 255. 


If either int-exp1 or int-exp2 is a floating-point expression, VAX BASIC 
truncates it to a LONG integer. 
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STRINGS 
Example 


DECLARE STRING output_str 


output_str = STRING$(10%, 50%) !50 is the ASCII value of the 
PRINT output_str !character "2" 


Output 
2222222222 
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The SUB statement marks the beginning of a VAX BASIC subprogram and 
specifies the number and data type of its parameters. 


Format 


SUB = sub-name [ pass-mech ] [ ( [ formal-param ],... ) ] 
[ statement ]... 


{ suseno. | 


7 BY REF 
aneeh 
ade BY DESC 


unsubs-var 
formal-param: [ data-type ] { array-name ( | on ey 


' 


[ = int-const ] [ pass-mech ] 


Syntax Rules 


1. Sub-name is the name of the separately compiled subprogram. 


2. Formal-param specifies the number and type of parameters for the 
arguments the SUB subprogram expects to receive when invoked. 


e Empty parentheses indicate that the SUB subprogram has no 
parameters. 
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Remarks 


° Data-type specifies the data type of a parameter. If you do not 
specify a data type, parameters are of the default data type and 
size. When you do specify a data type, all following parameters 
are of that data type until you specify a new data type. Data 
type keywords and their size, range, and precision are listed in 
Table 1-2 in this manual. 


Sub-name can have from 1 to 31 characters and must conform to the 
following rules: 


e The first character of an unquoted name must be an alphabetic 
character (A through Z). The remaining characters, if present, can 
be any combination of letters, digits (0 through 9), dollar signs 
($), periods (.), or underscores (_). 


e A quoted name can consist of any combination of printable ASCII 
characters. 


Data-type can be any VAX BASIC data type keyword or a data type 
defined by a RECORD statement. 


Pass-mech specifies the parameter passing mechanism by which the 
subprogram receives arguments. 


A pass-mech clause outside the parentheses applies by default to all 
SUB parameters. A pass-mech clause in the formal-param list overrides 
the specified default and applies only to the immediately preceding 
parameter. 


The SUB statement must be the first statement in the SUB subprogram. 


Compiler directives and comment fields created with an exclama- 
tion point (!), can precede the SUB statement because they are not 
VAX BASIC statements. Note that REM is a VAX BASIC statement; 
therefore, it cannot precede the SUB statement. 


Every SUB statement must have a corresponding END SUB statement 
or SUBEND statement. 


If you do not specify a passing mechanism, the SUB program receives 
arguments by the default passing mechanisms, as shown in Table 4-1. 


Parameters defined in formal-param must agree in number, type, 
ordinality, and passing mechanism with the arguments specified in the 
CALL statement of the calling program. 
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Example 


10. 


11. 


12. 


SUB 


END 


You can specify up to 255 parameters. 


Any VAX BASIC statement except those that refer to other program 
unit types (FUNCTION, PICTURE or PROGRAM) can appear in a 
SUB subprogram. 


All variables, except those named in MAP and COMMON statements 
are local to that subprogram. 


VAX BASIC initializes local variables to zero or the null string. 


SUB subprograms receive parameters by reference or by descriptor. A 
SUB subprogram cannot receive any parameter BY VALUE. Table 4-1 
lists and describes VAX BASIC parameter-passing mechanisms. 


e BY REF specifies that the subprogram receives the argument’s 
address. 


e BY DESC specifies that the subprogram receives the address of 
a VAX BASIC descriptor. For information about the format of a 
VAX BASIC descriptor for strings and arrays, see the VAX BASIC 
User Manual. For information on other types of descriptors, see 
the VAX Architecture Handbook. 


By default, VAX BASIC subprograms receive numeric unsubscripted 
variables by reference, and all other parameters by descriptor. You 
can override these defaults for strings and arrays with a BY clause: 


e If you specify a string length with the =int-const clause, you must 
also specify BY REF. If you specify BY REF and do not specify a 
string length, VAX BASIC uses the default string length of 16. 


e If you specify array bounds, you must also specify BY REF. 
Subprograms can be called recursively. 


SUB3 BY REF (DOUBLE A, B, & 
STRING Emp_nam BY DESC, & 
wage (20) ) 

SUB 
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The SUBEND statement is a synonym for the END SUB statement. See 
the END statement for more information. 


Format 
SUBEND 
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SUBEXIT 


The SUBEXIT statement is a synonym for the EXIT SUB statement. See 
the EXIT statement for more information. 


Format 
SUBEXIT 
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SUMS 


The SUM$ function returns a string whose value is the sum of two 
numeric strings. 


Format 


str-var = SUMS (str-exp1, str-exp2) 
Syntax Rules 
None. 
Remarks 


1. Each string expression can contain up to 54 ASCII digits and an 
optional decimal point and sign. 


2. VAX BASIC adds str-exp2 to str-exp1 and stores the result in str-var. 


3. If str-exp1 and str-exp2 are integers, str-var takes the precision of the 
larger string unless trailing zeros generate that precision. 


4. If str-exp1 and str-exp2 are decimal fractions, str-var takes the preci- 
sion of the more precise fraction, unless trailing zeros generate that 
precision. 


5. SUM$ omits trailing zeros to the right of the decimal point. 
6. The sum of two fractions takes precision as follows: 
e The sum of the integer parts takes the precision of the larger part. 


¢ The sum of the decimal fraction part takes the precision of the 
more precise part. 


7. SUMS$ truncates leading and trailing zeros. 
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DECLARE STRING A, B, total 
A = "46" 

B = "87" 

total = SUM$(A,B) 

PRINT total 


Output 
133 
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SWAP% 


The SWAP% function transposes a WORD integer’s bytes. 


NOTE 


The SWAP% function is supported only for compatibility with 
BASIC-PLUS-2. DIGITAL recommends that you do not use the 
SWAP% function for new program development. 


Format 


int-var = SWAP% (int-exp) 
Syntax Rules 
None. 
Remarks 


1. SWAP% is a WORD function. VAX BASIC evaluates int-exp and 
converts it to the WORD data type, if necessary. 


2. WAX BASIC transposes the bytes of int-exp and returns a WORD 
integer. 


Example 


DECLARE INTEGER word_int 
word_int = SWAP%(23) 
PRINT word_int 


Output 
5888 
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When used with the PRINT statement, the TAB function moves the cursor 
or print mechanism to a specified column. 


When used outside the PRINT statement, the TAB function creates a string 
containing the specified number of spaces. 


Format 


str-var =T AB (int-exp) 
Syntax Rules 


1. When used with the PRINT statement, int-exp specifies the column 
number of the cursor or print mechanism. 


2. When used outside the PRINT statement, int-exp specifies the number 
of spaces in the returned string. 


Remarks 


You cannot tab beyond the current MARGIN restriction. 
2. The leftmost column position is zero. 


3. If int-exp is less than the current cursor position, the TAB function has 
no effect. 


4. The TAB function can move the cursor or print mechanism only from 
the left to the right. 


5. You can use more than one TAB function in the same PRINT state- 
ment. 


6. Use semicolons to separate multiple TAB functions in a single state- 
ment. If you use commas, VAX BASIC moves to the next print zone 
before executing the TAB function. 
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7. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to LONG integer. 
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TAB 


PRINT "Number 1"; TAB(15); "Number 2"; TAB(30); "Number 3" 


Output 


Number 1 Number 2 Number 3 
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TAN 


The TAN function returns the tangent of an angle in radians or degrees. 


Format 


real-var =TAN (real-exp) 
Syntax Rules 


Real-exp is an angle specified in radians or degrees, depending on which 
angle clause you choose with the OPTION statement. 


Remarks 
VAX BASIC expects the argument of the TAN function to be a real 
expression. When the argument is a real expression, VAX BASIC returns 
a value of the same floating-point size. When the argument is not a real 
expression, VAX BASIC converts the argument to the default floating-point 
size and returns a value of the default floating-point size. 

Example 


OPTION ANGLE = DEGREES 
DECLARE REAL tangent 
tangent = TAN(45.0) 
PRINT tangent 


Output 
1 
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The TIME function returns the time of day (in seconds) as a floating- 
point number. The TIME function can also return process CPU time and 
connect time. 


Format 


real-var =TIME (int-exp) 
Syntax Rules 
None. 
Remarks 


1. The value returned by the TIME function depends on the value of 
int-exp. 


2. If int-exp equals zero, TIME returns the number of seconds since 
midnight. 


3. VAX BASIC also accepts values 1 and 2 and returns values as shown 
in Table 4-7. All other arguments to the TIME function are undefined 
and cause VAX BASIC to signal “Not implemented” (ERR=250). 


4. The TIME function returns a SINGLE floating-point value. 


5. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to a LONG integer. 
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TIME 


Table 4—7: TIME Function Values 


Argument Value: 
0 
1 


Example 


PRINT TIME(0) 


Output 
49671 
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VAX BASIC Returns: 
The amount of time elapsed since midnight in seconds 


The CPU time of the current process in tenths of a 
second 


The connect time of the current process in minutes 


TIMES 


TIMES 


The TIME$ function returns a string displaying the time of day in the form 
hh:mm AM or hh:mm PM. 


Format 


str-var =TIMES§ (int-exp) 
Syntax Rules 
Int-exp specifies the number of minutes before midnight. 
Remarks 


If int-exp equals zero, TIME$ returns the current time of day. 


2. The value of int-exp must be between 0 and 1440 or VAX BASIC 
signals an error. 


3. The TIME$ function uses a 12-hour, AM/PM clock. Before 12:00 
noon, TIME$ returns hh:mm AM, and after 12:00 noon, hh:mm PM. 


4. If you specify a floating-point expression for int-exp, VAX BASIC 
truncates it to a LONG integer. 


DECLARE STRING current_time 
current_time = TIME$(0) 
PRINT current_time 


Output 
01:51 PM 
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TRMS 


The TRM$ function removes all trailing blanks and tabs from a specified 
string. 


Format 


str-var =TRMS$ (str-exp) 
Syntax Rules 
None. 
Remarks 


The returned str-var is identical to str-exp, except that it has all the trailing 
blanks and tabs removed. 


DECLARE STRING old_string, new_string 
old_string = "ABCDEFG " 
new_string = TRM$(old_string) 

PRINT old_string; "XYZ" 

PRINT new_string; "XYZ" 


Output 


ABCDEFG XYZ 
ABCDEFGXYZ 
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The UBOUND function returns the upper bounds of a compile-time or 
run-time dimensioned array. 


Format 


num-var = UBOUND (array-name [ , num-exp J) 
Syntax Rules 


1. Array-name must specify an array that has been previously explicitly 
or implicitly declared. 


2. Num-exp specifies the number of the dimension for which you have 
requested the upper bound. 


Remarks 


1. If you do not specify a numeric expression, VAX BASIC automatically 
returns the upper bound of the first dimension. 


2. If you specify a numeric expression that is less than or equal to zero, 
VAX BASIC signals an error message. 


3. If you specify a numeric expression that exceeds the number of 
dimensions, VAX BASIC signals an error message. 
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DECLARE INTEGER CONSTANT B = 5 

DIM A(B) 

account_num = 1 

FOR dim_num = 0 TO UBOUND(A) 
A(dim_num) = account_num 
account_num = account_num + i 
PRINT A(dim_num) 

NEXT dim_num 


Output 


Oonr WH & 
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UNLESS 


The UNLESS qualifier modifies a statement. VAX BASIC executes the 
modified statement only if a conditional expression is false. 


Format 


statement UNLESS cond-exp 
Syntax Rules 
None. 
Remarks 


1. The UNLESS statement cannot be used on nonexecutable statements 
or on statements such as SELECT, IF, and DEF that establish a 
statement block. 


2. VAX BASIC executes the statement only if cond-exp is false (value 
zero). 


Example 


PRINT "A DOES NOT EQUAL 3" UNLESS A% = 3% 


Statements and Functions 4-375 


UNLOCK 


UNLOCK 


The UNLOCK statement unlocks the current record or bucket locked by 
the last FIND or GET statement. 


Format 
UNLOCK #chnil-exp 


Syntax Rules 


Chnl-exp is a numeric expression that specifies a channel number asso- 
ciated with a file. It must be immediately preceded by a number sign 


(#). 
Remarks 


1. A file must be opened on the specified channel before UNLOCK can 
execute. 


2. The UNLOCK statement only applies to files on disk. 


3. If the current record is not locked by a previous GET or FIND state- 
ment, the UNLOCK statement has no effect and VAX BASIC does not 
signal an error. 


4. The UNLOCK statement does not affect record buffers. 


5. After VAX BASIC executes the UNLOCK statement, you cannot 
update or delete the current record. 


6. Once the UNLOCK statement executes, the position of the current 
record pointer is undefined. 
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Example 


UNLOCK #10% 
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UNTIL 


The UNTIL statement marks the beginning of an UNTIL loop or modifies 
the execution of another statement. 


Format 
Conditional 
UNTIL cond-exp 
[ statement ]... 
NEXT 


Statement Modifier 
statement UNTIL cond-exp 


Syntax Rules 
None. 
Remarks 


1. Conditional 
_ © A NEXT statement must end the UNTIL loop. 


e VAX BASIC evaluates cond-exp before each loop iteration. If the 
expression is false (value zero), VAX BASIC executes the loop. If 
the expression is true (value nonzero), control passes to the first 
executable statement after the NEXT statement. 
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2. Statement Modifier 
VAX BASIC executes the statement repeatedly until cond-exp is true. 


Example 1 


!Conditional 
UNTIL A >= 5 
A =A+ .01 
TOTAL = TOTAL + 1 
NEXT 


Example 2 


!'Statement Modifier 
A = A + 1 UNTIL A >= 200 
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The UPDATE statement replaces a record in a file with a record in the 
record buffer. The UPDATE statement is valid on sequential, relative, and 
indexed files. 


Format 


UPDATE #chnil-exp [, COUNT int-exp / 
Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number 
associated with a file. It must be immediately preceded by a number 
sign (#). 


2. Int-exp specifies the size of the new record. 
Remarks 


1. The file associated with chnl-exp must be a disk file opened with 
ACCESS MODIFY. 


2. Each UPDATE statement must be preceded by a successful GET or 
FIND operation or VAX BASIC signals “No current record” (ERR=131). 
FIND locates but does not retrieve records. Therefore, you must 
specify a COUNT clause when retrieving variable-length records 
when the preceding operation was a FIND. Int-exp must exactly match 
the size of the old record. 


3. If you are updating a variable-length record, and the record that you 
want to write out is not the same size as the record you retrieved, you 
must use a COUNT clause. 


. 4, After an UPDATE statement executes, there is no current record 
pointer. The next record pointer is unchanged. 
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UPDATE 


The length of the new record must be the same as that of the existing 
record for all files with fixed-length records and for all sequential files. 
If you specify a COUNT clause, the int-exp must match the size of the 
existing record. 


For relative files with variable-length records, the new record can be 
larger or smaller than the record it replaces. 


e¢ The new record must be smaller than or equal to the maximum 
record size set with the MAP or RECORDSIZE clause when the 
file was opened. 


e¢ You must use the COUNT clause to specify the size of the new 
record if it is different from that of the record last accessed by a 
GET operation on that channel. 


For indexed files with variable-length records, the new record can be 
larger or smaller than the record it replaces. When the program does 
not permit duplicate primary keys, the new record can be no longer 
than the size specified by the MAP or RECORDSIZE clause when the 
file was opened. The record must include at least the primary key 
field. 


An indexed file alternate key for the new record can differ from that 
of the existing record only if the OPEN statement for that file specified 
CHANGES for the alternate key. 


UPDATE #4%, COUNT 32 
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VAL 


The VAL function converts a numeric string to a floating-point value. 


NOTE 


DIGITAL recommends that you use the DECIMAL, REAL, and 
INTEGER functions to convert numeric strings to numeric data 


types. 


Format 


real-var = VAL (str-exp) 
Syntax Rules 


Str-exp can contain the ASCII digits 0 through 9, uppercase E, a plus sign 
(+), a minus sign (—), and a period (.). 


Remarks 


1. The VAL function ignores spaces and tabs. 


2. If str-exp is null, or contains only spaces and tabs, VAL returns a value 
of zero. 


3. The value returned by the VAL function is of the default floating-point 
size. 
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DECLARE REAL real_num 
real_num = VAL("990.32") 
PRINT real_num 


Output 
990 . 32 
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VAL 


VAL% 


The VAL% function converts a numeric string to an integer. 


NOTE 


DIGITAL recommends that you use the DECIMAL, REAL, and 
INTEGER functions to convert numeric strings to numeric data 


types. 


Format 


int-var = VAL% (str-exp) 
Syntax Rules 


Str-exp can contain the ASCII digits 0 through 9, a plus sign (+), or a 
minus sign (—). 


Remarks 


The VAL% function ignores spaces and tabs. 


2. If str-exp is null or contains only spaces and tabs, VAL% returns a 
value of zero. 


3. The value returned by the VAL% function is an integer of the default 
size. 
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DECLARE INTEGER ret_int 
ret_int = VAL%,("789") 
PRINT ret_int 


Output 
789 
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VMSSTATUS 


VMSSTATUS 


VMSSTATUS returns the underlying VAX/VMS condition code when 
control is transferred to a VAX BASIC error handler. 


Format 
int-var = VMSSTATUS 


Syntax Rules 
None. 
Remarks 


1. If ERR contains the value 194, you can specify VMSSTATUS to 
examine the actual error that was signaled to VAX BASIC. 

2. If an error is raised by an underlying system component such as the 
Run-Time Library, you can specify VMSSTATUS to determine the 
underlying error. 


3. If you are writing a utility routine that may be called from languages 
other than VAX BASIC, you can specify VMSSTATUS in a call to 
LIB$SIGNAL to signal the underlying error to the caller of the utility 
routine. 


4, When there is no error pending, VMSSTATUS remains undefined. 
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VMSSTATUS 


PROGRAM 
WHEN ERROR USE global_handler 


END WHEN 


HANDLER global_handler 
final_status% = VMSSTATUS 
END HANDLER 

END PROGRAM final_status% 
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WAIT 


WAIT 


The WAIT statement specifies the number of seconds the program waits 
for terminal input before signaling an error. 


Format 


WAIT _int-exp 
Syntax Rules 


Int-exp must be between 0 and 255; if it is greater than 255, VAX BASIC 
assumes a value of 255. 


Remarks 


1. The WAIT statement must precede a GET operation to a terminal or 
an INPUT, INPUT LINE, LINPUT, MAT INPUT, or MAT LINPUT 
statement. Otherwise, it has no effect. 


2. Int-exp is the number of seconds VAX BASIC waits for input before 
signaling the error, “Keyboard wait exhausted” (ERR=15). 


3. After VAX BASIC executes a WAIT statement, all input statements 
wait the specified amount of time before VAX BASIC signals an error. 


4. WAIT 0 disables the WAIT statement. 
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WAIT 


10 DECLARE STRING your_name 
WAIT 60 
INPUT "You have sixty seconds to type your name"; your_nane 
WAIT O 


Output 


You have sixty seconds to type your name? 

“BAS-F-KEYWAIEXH, Keyboard wait exhausted 

-BAS-I-ON_CHAFIL, on channel O for file SYS$INPUT:.; at user PC 00000644 
-RMS-W-TMO, timeout period expired 

-~BAS-I-FROLINMOD, from line 10 in module WAIT 

“.TRACE-F-TRACEBACK, symbolic stack dump follows 

module name routine name line rel PC abs PC 


00007334 00007334 
sos-- above condition handler called with exception 001A807C: 
%BAS-F-KEYWAIEXH, keyboard wait exhausted 
~BAS-I-ON_CHAFIL, on channel O for file SYS$INPUT:.; at user PC 00000644 
-RMS-W-TMO, timeout period expired 
sss end of exception message 

00011618 00011618 
OOOOFO2F OOOOFO2F 
OOOOE3F6 OOOOE3F6 
0001387A 0001387A 
WAIT$MAIN WAIT$MAIN 3 00000044 00000644 
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WHEN ERROR 


The WHEN ERROR statement marks the beginning of a WHEN ERROR 
construct. The WHEN ERROR construct contains a protected region and 
can include an attached handler or identify a detached handler. 


Format 


With an Attached Handler 


WHEN ERROR IN 
protected-statement 
[ protected-statement,... ] 


USE 
handler-statement 
[ handler-statement,... ] 


END WHEN 


With a Detached Handler 
WHEN ERROR USE __handler-name 


protected-statement 
[ protected-statement.,... ] 


END WHEN 
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HANDLER _handler-name 


handler-statement... 


END HANDLER 


Syntax Rules 


Protected-statement specifies a statement that appears within a pro- 
tected region. A protected region is a special block of code that is 
monitored by VAX BASIC for the occurrence of a run-time error. 


Handler-statement specifies the statement that appears inside an error 

handler. 

With an Attached Handler 

e The keyword USE marks the start of handler statements. 

e An attached handler must be delimited by a USE and END WHEN 
statement. 

With a Detached Handler 

e¢ The keyword USE names the associated handler for the protected 
region. 

¢ Handler-name must be a valid VAX BASIC identifier and cannot be 


the same as any label, DEF, DEF*, SUB, FUNCTION or PICTURE 
name within the same program unit. 


e A detached handler must be delimited by a HANDLER and END 
HANDLER statement. 


e You can specify the same detached handler with more than one 
WHEN ERROR USE statement. 
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WHEN ERROR 


Remarks 


a 


10. 


11. 


12, 


The WHEN ERROR statement designates the start of a block of 
protected statements. 


If an error occurs inside a protected region, VAX BASIC transfers 
control to the error handler associated with the WHEN ERROR 
statement. 


VAX BASIC does not allow you branch into a WHEN block. 


When VAX BASIC encounters an END WHEN statement for an 
attached handler or an END HANDLER statement for a detached 
handler, VAX BASIC clears the exception and transfers control to the 
following statement. 


VAX BASIC allows you to nest WHEN blocks. If an exception occurs 
within a nested protected region, VAX BASIC transfers control to the 
handler associated with the innermost protected region in which the 
error occurred. 

WHEN blocks cannot exist inside a handler. 

WHEN blocks cannot cross other block structures. 


You cannot specify a RESUME statement within a WHEN ERROR 
construct. 


You cannot specify an ON ERROR statement within a protected 
region. 

An attached handler must immediately follow the protected region of 
a WHEN ERROR IN block. 


Exit from a handler must occur through a RETRY, CONTINUE, or 
EXIT HANDLER statement, or by reaching the end of the handler 
delimited by END WHEN or END HANDLER. 


For. more information about detached handlers, see the HANDLER 
statement. 
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Examples 


Example 1 


‘With an attached handler 
PROGRAM salary 
DECLARE REAL hourly_rate, no_of_hours, weekly_pay 
WHEN ERROR IN 
INPUT "Enter your hourly rate";hourly_rate 
INPUT "Enter the number of hours you worked this week" ;no_of_hours 
weekly_pay = no_of_hours * hourly_rate 
PRINT "Your pay for this week is";weekly_pay 


USE 
SELECT ERR 
CASE = 50 
PRINT "Invalid data" 
RETRY 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END WHEN 
END PROGRAM 


Output 1 


Enter your hourly rate? 35.00 
Enter the number of hours you worked this week? 45 
Your pay for this week is 1575 


Example 2 


!'With a detached handler 
PROGRAM salary 
DECLARE REAL hourly_rate, no_of_hours, weekly_pay 
WHEN ERROR USE patch_work 
INPUT "Enter your hourly rate" ;hourly_rate 
INPUT "Enter the number of hours you worked this week" ;no_of_hours 
weekly_pay = no_of_hours * hourly_rate 
PRINT "Your pay for this week is"; weekly_pay 
END WHEN 
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WHEN ERROR 


HANDLER patch_work 
SELECT ERR 
CASE = 50 
PRINT "Invalid data" 
RETRY 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END HANDLER 
END PROGRAM 


Output 2 


Enter your hourly rate? Nineteen dollars and fifty cents 
Invalid data 

Enter your hourly rate? 19.50 

Enter the number of hours you worked this week? 40 

Your pay for this week is 780 
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WHILE 


WHILE 


The WHILE statement marks the beginning of a WHILE loop or modifies 
the execution of another statement. 


Format 
Conditional 
WHILE = cond-exp 
[ statement ]... 
NEXT 


Statement Modifier 


statement WHILE cond-exp 
Syntax Rules 
A NEXT statement must end the WHILE loop. 
Remarks 


1. Conditional 


VAX BASIC evaluates cond-exp before each loop iteration. If the 
expression is true (value nonzero), VAX BASIC executes the loop. 
If the expression is false (value zero), control passes to the first 
executable statement after the NEXT statement. 
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WHILE 


2. Statement Modifier 


VAX BASIC executes the statement repeatedly as long as cond-exp is 
true. 


Examples 


Example 1 


{Conditional 
WHILE X < 100 

X = X + SQR(X) 
NEXT 


Example 2 


{Statement Modifier 
X% = X% + 1% WHILE x% < 100% 
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XLATES 


XLATES 


The XLATE$ function translates one string to another by referencing a 
table string you supply. 


Format 


str-var = XLATE[$] (str-exp1, str-exp2) 


Syntax Rules 
1. 
> 

Remarks 
1: 
ya 
3. 


Str-exp1 is the input string. 
Str-exp2 is the table string. 


Str-exp2 can contain up to 256 ASCII characters, numbered from 0 

to 255; the position of each character in the string corresponds to an 
ASCII value. Because 0 is a valid ASCII value (null), the first position 
in the table string is position zero. 


XLATE$ scans str-exp1 character by character, from left to right. It 
finds the ASCII value n of the first character in str-exp1 and extracts 
the character it finds at position n in str-exp2. XLATE$ then appends 
the character from str-exp2 to str-var. XLATE$ continues this process, 
character by character, until the end of str-exp1 is reached. 


The output string may be smaller than the input string for the follow- 
ing reasons: 
e XLATE$ does not translate nulls. If the character at position n 


in str-exp2 is a null, XLATE$ does not append that character to 
str-var. 


e If the ASCII value of the input character is outside the range of 
positions in str-exp2, XLATE$ does not append any character to 
str-var. 
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XLATES 


Example 


DECLARE STRING A, table, source 

A = "“abcdefghijklmnopqrstuvwxyz" 

table = STRING$(65, 0) + A 

LINPUT "Type a string of uppercase letters"; source 
PRINT XLATE$(source, table) 


Output 


Type a string of uppercase letters? ABCDEFG 
abcdefg 
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Appendix A 


Transporting Programs Between VAX 
BASIC and BASIC-PLUS-2 


This appendix summarizes transportability issues between BASIC-PLUS-2 
and VAX BASIC. 


A.1 Overview 


This appendix is for users who want to write BASIC programs that can 
be used in both VAX BASIC and PDP-11 BASIC-PLUS-2. It describes 
functionality that is particular to one language, as well as statements and 
functions that appear the same in both languages, but produce different 
results. . 


Note that this appendix does not describe all the differences between 
VAX BASIC and BASIC-PLUS-2. To assist you in writing transportable 
programs, use the DCL command BASIC/FLAG=BP2COMPATIBILITY 
when you invoke VAX BASIC. This command causes VAX BASIC to signal 
an informational message whenever you use functionality that is not 
compatible with BASIC-PLUS-2. 


This appendix contains the following sections: 
e Language-specific functionality 

e 1/O differences 

e Procedure calling 

e Generated errors 

¢ Miscellaneous differences 
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A.2 Language-Specific Functionality 


The following statements, functions, and clauses are available only in 
BASIC-PLUS-2: 


Specifying a line number with the CHAIN statement tf 

The FSS$ function 

The ONECHR function (see the VAX BASIC INKEY$ function) 
The PEEK function + 

The SPEC% function t 

The CLUSTERSIZE and MODE clauses on the OPEN statement f 


VAX BASIC supports the following functionality which is not available in 
BASIC-PLUS-2: 


Graphics 

Support for the VAX Language-Sensitive Editor 
Non-zero lower bounds for arrays 

WHEN blocks 


Return values on the END, EXIT DEF, END DEF, EXIT FUNCTION, 
and END FUNCTION statements 


Dollar sign ($) and percent sign (%) suffixes in explicitly declared 
variables 


User-defined data types with the RECORD statement 
DECIMAL, GFLOAT, and HFLOAT data types 
Hexadecimal, binary, and octal literal notation 


The following statements, functions, and commands are available only in 
VAX BASIC: 


The %DECLARED directive 

The %INCLUDE %FROM %CDD directive 
The %INCLUDE %FROM %LIBRARY directive 
The %PRINT directive 

All graphics statements 

The CAUSE ERROR statement 


t Specific to BASIC-PLUS-2 on RSTS/E systems. 
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e The FREE statement 


e The FIND statement with the ALLOW, REGARDLESS, and WAIT 
clauses 


e The GET statement with the ALLOW, REGARDLESS, and WAIT 
clauses 


¢ The MID$ assignment statement 


e The OPTION CONSTANT TYPE, OPTION HANDLE, and OPTION 
ANGLE statements 


e The PROGRAM, END PROGRAM and EXIT PROGRAM statements 
e¢ The RECORD statement 


e All WHEN block statements and clauses (WHEN...END WHEN, 
HANDLER...END HANDLER, CONTINUE, RETRY, and EXIT 
HANDLER) 


e The DECIMAL function 

e The INKEY$ function 

e The LBOUND and UBOUND functions 

e The LOC function 

e The MARGIN and NOMARGIN functions 

e The MAX, MIN, and MOD functions 

e The VMSSTATUS and RMSSTATUS functions 


e The ANY and OPTIONAL keywords in EXTERNAL routine declara- 
tions 


A.3 1/0 Differences 


This section discusses some I/O differences between VAX BASIC and 
BASIC-PLUS-2. 


A.3.1 The MAGTAPE Function 
VAX BASIC does not support the MAGTAPE function except for the 


rewind tape function (code 3). Table A-1 describes the VAX BASIC 
actions you can perform to obtain other MAGTAPE functionality. 
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Table A-1: MAGTAPE Functionality in VAX BASIC 


Code Function VAX BASIC Action 

2 Write EOF Close channel with the CLOSE statement 

3 Rewind tape Use the RESTORE # statement, the REWIND clause 
on an OPEN statement, or the MAGTAPE function 

4 Skip records Perform GET operations, ignore data until reaching 
desired record 

5 Backspace Rewind tape, perform GET operations, ignore data 
until reaching desired record 

6 Set density or set parity Use the DCL commands MOUNT/DENSITY and 
MOUNT/FOREIGN or the $MOUNT system service 

7 Get status Use the RMSSTATUS function 


A.3.2 The OPEN Statement 


The following differences exist in the OPEN statement when used in VAX 
BASIC and BASIC-PLUS-2: 


e In VAX BASIC, a map named in an OPEN statement is never initial- 
ized; in BASIC-PLUS-2, variables in the map are initialized to zero or 
to the null string. 


e In VAX BASIC, an OPEN error causes the STATUS variable to be 
set to zero. In BASIC-PLUS-2, an OPEN error causes the STATUS 
variable to be set to the RMS STS field value. Use the VAX BASIC 
RMSSTATUS function to return the RMS STS field value. 


e Both VAX BASIC and BASIC-PLUS-2 allow you to omit key clauses 
when opening an existing indexed fie. However, VAX BASIC requires 
that you explicitly specify FOR INPUT; BASIC-PLUS-2 does not. 


The following OPEN statement clauses produce different results when 
used in VAX BASIC and BASIC-PLUS-2: 


e The ALLOW Clause 


VAX BASIC requires that you have write access to a file in order to 
specify ALLOW NONE in an OPEN statement; BASIC-PLUS-2 does 
not. 
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The CLUSTERSIZE Clause 


The CLUSTERSIZE clause can be used with an OPEN statement on 
RSTS/E systems only. In VAX BASIC and BASIC-PLUS-2 on RSX 
systems, you can obtain functionality similar to the CLUSTERSIZE 
clause by using the EXTENDSIZE and WINDOWSIZE clauses. The 
EXTENDSIZE clause specifies the amount of space a file is extended 
after the existing space is full. The WINDOWSIZE clause specifies the 
number of block retrieval pointers that are kept in memory for the file. 


The CONTIGUOUS Clause 


In VAX BASIC, using the CONTIGUOUS clause with an OPEN 
statement does not necessarily mean the file will occupy contiguous 
disk space. If there is not enough contiguous space available, RMS 
allocates the largest possible contiguous space and does not signal 
an error. In BASIC-PLUS-2, if there is not enough contiguous space 
available, RMS signals an error. 


The MODE Clause 


The MODE clause cannot be used with an OPEN statement in VAX 
BASIC. In BASIC-PLUS-2 on RSX systems, the MODE clause is 
ignored except when used for device-specific I/O. Table A-2 lists 
transportable BASIC statements that correspond to RSTS/E disk 
MODE values. You can use these statements in VAX BASIC as well as 
in BASIC-PLUS-2 on RSX systems. 
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Table A-—2: 


MODE 
Value 


0% 
1% 
2% 
5% 
16% 


32% 
64% 


4096% 
8192% 


1 


Function 


Normal read/write 


Update file 
Append to file 
Update file 


Create contiguous 
Create tentative file 


Create contiguous file 
conditionally 


Read only regardless 
Read Only 


The REGARDLESS clause is not available in BASIC-PLUS-2. 


The RECORDSIZE Clause 


RSTS/E Disk MODE Values and Corresponding BASIC 
Statements 


Transportable Statement 


Use OPEN with ACCESS MODIFY and 
ALLOW MODIFY 


Use OPEN with ACCESS MODIFY 
Use OPEN with ACCESS APPEND 


Use OPEN with ACCESS MODIFY and 
ALLOW MODIFY 


Use OPEN with CONTIGUOUS 
Use OPEN with TEMPORARY 
Use OPEN with CONTIGUOUS 


Use GET or FIND with REGARDLESS! 
Use OPEN with ACCESS READ 


In all VAX BASIC files and BASIC-PLUS-2 RMS files, the 
RECORDSIZE clause specifies the RMS logical record size. In BASIC- 
PLUS-2 virtual files, the RECORDSIZE clause specifies the size of the 


I/O buffer for the channel. 


A.3.3 The PUT Statement 


In VAX BASIC, a PUT statement with a count of zero to a variable length 
file creates a record with a length of zero; in BASIC-PLUS-2, the size of 
the record created is the size specified in the RECORDSIZE clause or, if no 
RECORDSIZE clause is specified, the length of the longest map. 
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A.4 Procedure Calling 


This section discusses some differences in procedure calling between VAX 
BASIC and BASIC-PLUS-2. 


A.4.1. The CALL Statement 


The following difference occur in the CALL statement when used in VAX 
BASIC and BASIC-PLUS-2: 


In VAX BASIC, you can use the CALL statement to call a procedure 
that is written in any language which supports the VAX Procedure 
Calling Standard. In BASIC-PLUS-2, you can use the CALL statement 
to call only BASIC-PLUS-2 and MACRO subprograms. 


In VAX BASIC, individual array element parameters (except virtual 
array elements) are passed by reference and are modifiable. In BASIC- 
PLUS-2, individual array element parameters are passed by local copy 
and are not modifiable. 


VAX BASIC does not allow passing of entire virtual arrays; BASIC- 
PLUS-2 allows passing of entire virtual arrays. 


In VAX BASIC, you can pass up to 255 parameters in each subpro- 
gram. In BASIC-PLUS-2, you can pass up to 8 parameters in each 
subprogram. 


A.4.2 The CHAIN Statement 


In VAX BASIC and in BASIC-PLUS-2 on RSX systems, you cannot specify 
a line number in a CHAIN statement. In BASIC-PLUS-2 on RSTS/E 
systems, line numbers are allowed. 
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A.4.3 SYS and FIP SYS Calis 


VAX BASIC supports a subset of RSTS/E SYS and FIP calls. These are 
summarized in Tables A-3 and A-4. 


Table A-3: 


Function 
Code 


0 


reP OO WAN HD WW N 


Table A-4: 


Function 
Code 


-23 
-13 
-10 
-7 
9 
10 
11 
12 
18 
22 


VAX BASIC Subset of RSTS/E SYS Calis 


Function 

Cancel CTRL/O effect on terminal 
Enable echoing on terminal 
Disable echoing on terminal 

Exit with no prompt message 

SYS call to the file processor 

Get core common string 

Put core common string 

Exit and clear program 


Cancel all type ahead 


VAX BASIC Subset of RSTS/E FIP SYS Calls 


Function 

Terminate file name string scan 

Change priority/run burst/job size 

Begin file name string scan 

Enable CTRL/C trap 

Return error messages 

Assign user logical 

Deallocate a device or deassign user logical 
Deallocate all devices 

Obsolete (use function code 22) 


Message send/receive 


Note that the FIP call for sending or receiving messages (code 22) pro- 
duces different results when used in VAX BASIC and BASIC-PLUS-2 on 
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RSTS/E systems. In VAX BASIC, a receiver identification is removed from 
the receiver table when the image that declared it exits; in BASIC-PLUS-2 
on RSTS/E systems, a receiver identification stays in the receiver table 
until it is explicitly removed or the job terminates. This difference causes 
incompatible behavior with chained programs, because in VAX BASIC 

the receiver identification is valid only for the program that declares it; 
whereas in BASIC-PLUS-2 on RSTS/E systems, the chained programs can 
share a receiver identification. DIGITAL recommends the use of mailboxes 
or DECnet task-to-task communication as a replacement for these FIP calls 
in VAX BASIC. 


A.5 Generated Errors 


In VAX BASIC and BASIC-PLUS-2, the same errors are handled differently 
or signal different error messages and numbers: 


e If you press CTRL/Z after responding to an INPUT statement, VAX 
BASIC makes the assignment and signals the error “End of file on 
device” (ERR=11) when the next INPUT statement executes; BASIC- 
PLUS-2 signals the same error, does not make the assignment, and 
terminates the current input line. 


e When nonnumeric or floating-point data is input to an INPUT or 
READ statement expecting numeric or integer data, VAX BASIC 
signals the error “Data format error” (ERR=50); BASIC-PLUS-2 signals 
the error “Illegal number” (ERR=52). 

e When the integer index of a FOR loop exceeds the default inte- 
ger size, VAX BASIC signals the error “Integer error or overflow” 
(ERR=51); BASIC-PLUS-2 signals the error “Integer overflow, FOR 
loop” (ERR=60). 

e When a program opens channel 0, VAX BASIC signals the error 
“Illegal I/O channel” (ERR=46); BASIC-PLUS-2 signals the error “I/O 
channel already open at line <line number> ” (ERR=7). 


e If no error handler is active, the errors in Table A-5 are fatal errors in 
VAX BASIC, but warnings in BASIC-PLUS-2. 
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Table A-5: Fatal Errors in VAX BASIC That Are Warnings in 


BASIC-PLUS-2 


Error 

Number Message 

48 Floating point error 

51 Integer error 

52 Illegal number 

53 Illegal argument in LOG 
54 Imaginary square roots 
61 Division by zero 


When a user has WRITE access to a block in a virtual file and a second 
user attempts to access that block, VAX BASIC and BASIC-PLUS-2 
on RSX signal the error “Record/bucket locked” (ERR=154); BASIC- 
PLUS-2 on RSTS/E signals the error “Disk block is interlocked” 
(ERR=19). 


A.6 Miscellaneous Differences 


This section discusses some miscellaneous differences between VAX BASIC 
and BASIC-PLUS-2. 


A.6.1 Data Types 


VAX BASIC supports DECIMAL, HFLOAT, GFLOAT and user-defined 
data types; BASIC-PLUS-2 does not. In BASIC-PLUS-2, as an alternative 
to the DECIMAL data type, use the DOUBLE data type with the OPTION 
SCALE statement or the SCALE command to minimize floating-point 
inaccuracy. 


A.6.2. The DEF and DEF« Statements 


In VAX BASIC, you can specify a maximum of 255 parameters in a DEF 
statement and a maximum of 8 parameters in a DEF* statement; in BASIC- 
PLUS-2, you can specify a maximum of 8 amen in both the DEF and 
DEF* statements. 
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A.6.3 Default Integer Size 


If you do not specify a default integer size when invoking VAX BASIC, the 
default integer size is LONGWORD; in BASIC-PLUS-2, the default integer 
size is WORD. In VAX BASIC, use the OPTION SIZE=INTEGER WORD 
statement or the COMPILE/WORD command to make BASIC-PLUS-2 
programs transportable to VAX BASIC. 


A.6.4 Integer Overflow 


When performing integer arithmetic, VAX BASIC signals an error message 
if the size of the value returned exceeds the default integer size. BASIC- 
PLUS-2 does not signal an error message, truncates the result, and returns 
a signed integer quantity. 


To disable error checking for integer overflow in VAX BASIC, use the 
OPTION INACTIVE=INTEGER OVERFLOW statement or the DCL com- 
mand BASIC/CHECK=NOOVERFLOW. 


A.6.5 Line Numbers and Labels 


In VAX BASIC, line numbers are optional. In BASIC-PLUS-2, you need at 
least one line number in each program. 


In a VAX BASIC program, labels, compiler directives, and comments can 
begin in column zero. In BASIC-PLUS-2, they cannot. 


A.6.6 The MAP and COMMON Statements 


The MAP and COMMON statements have different functionality when 
used in VAX BASIC and BASIC-PLUS-2. The differences are as follows: 


e In VAX BASIC, both COMMON areas and maps can have names 
containing a maximum of 31 characters and include underscore (_) 
characters. In BASIC-PLUS-2, COMMON areas and maps can have 
names containing a maximum of six characters; underscore characters 
are not allowed. 


Transporting Programs Between VAX BASIC and BASIC-PLUS-2 A-11 


If two strings overlap in a map, VAX BASIC performs string as- 
signments as if no overlap exists; BASIC-PLUS-2 performs string 
assignments one character at a time from left to right. (Note that 
RSET assignment is performed from right to left.) For example: 


10 MAP (FOO) A$ = 5 
MAP (FOO) FILL$ = 2, B$ = 5 
A$ = 'ABCDE' 
PRINT A$ 
BS = A$ 
PRINT B$, A$ 


When you run this program in VAX BASIC, the following output is 
displayed: 

ABCDE 

ABCDE ABABC 


When you run this program in BASIC-PLUS-2, the following output is 
displayed: 


ABCDE 
ABABA ABABA 


A.6.7 The MAP DYNAMIC Statement 


The following differences occur in the MAP DYNAMIC statement when 
used in VAX BASIC and BASIC-PLUS-2: 


If the MAP DYNAMIC statement is in an external subprogram or 
function, BASIC-PLUS-2 resets all pointers to the first byte each time 
the external module is called. VAX BASIC initializes the map area 
once when the external module is first called, and does not reset the 
variables pointers on subsequent calls. 


VAX BASIC allows you to specify a PSECT name or a static string 
variable in a MAP DYNAMIC statement; BASIC-PLUS-2 allows you 
to specify only a PSECT name. 


A.6.8 The PRINT Statement 


In VAX BASIC and RSX BASIC-PLUS-2, when you print to a terminal- 
format file and the line is to exceed 72 characters, you must either specify 
a record size, or a map, or use the VAX BASIC MARGIN function; this is 
not the case in BASIC-PLUS-2 on RSTS/E. 
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A.6.9 The PRINT USING Statement 


A.6.10 


A.6.11 


A.6.12 


A.6.13 


In VAX BASIC, the PRINT USING string formatting characters (L,R,C, 
and E) can be either uppercase or lowercase. In BASIC-PLUS-2, string 
formatting characters must be uppercase; otherwise, they are treated as 
string literals. 


The REPLACE Command 


In VAX BASIC, the REPLACE command writes the source program to 

the device and directory you specify in the OLD command. In BASIC- 
PLUS-2, the REPLACE command writes the source program to the current 
directory. 


The SPEC% and PEEK Functions 


You can use the SPEC% and PEEK functions only on RSTS/E systems. 
These functions are not transportable. 


String Comparisons 


When making string comparisons in all relational operations, VAX BASIC 
pads the shorter string with a blank space (ASCII value 32). BASIC-PLUS- 
2 pads the shorter string with a blank space only on equals (=) and not 
equals ( <> ) relational operations. 


Assigning Symbols 


In VAX BASIC, you use the logical name SYS$CURRENCY to change the 
currency symbol, SYS$RADIX_POINT to change the radix point symbol, 
and SYS$DIGIT_SEP to change the separator symbol. In BASIC-PLUS-2, 
you select the symbols for currency, radix point, and separator when 
installing the compiler. 
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A.6.14 The TIME Function 


The numeric arguments to the TIME function have different results 
when used in VAX BASIC and BASIC-PLUS-2. These differences are 
summarized in Table A-6. 


Table A-6: VAX BASIC and BASIC-PLUS-2 TIME Function 


Differences 

TIME 

Argument Result 

=s.  °  -) —)Cioe ah aa APIROAP HAST unk. cE ACTS CT TIGL n. “EME Cee age 

0 In both VAX BASIC and BASIC-PLUS-2, TIME returns the 
number of seconds that elapsed since midnight. 

1 In VAX BASIC and BASIC-PLUS-2 on RSTS/E systems, TIME 
returns the current job’s CPU time in tenths of a second. 

2 In VAX BASIC and BASIC-PLUS-2 on RSTS/E systems, TIME 
returns the current job’s connect time in minutes. 

3 In VAX BASIC, TIME returns zero. In BASIC-PLUS-2 on 
RSTS/E systems, TIME returns kilo-core ticks. 

4 In VAX BASIC, TIME returns zero. In BASIC-PLUS-2 on 


RSTS/E systems, TIME returns device time in minutes. 


‘Zero is the only valid argument for TIME in BASIC-PLUS-2 on RSX systems. 


A.6.15 The TIMES Function 


In VAX BASIC, the value returned by the TIME$ function is always dis- 
played in AM/PM format. In BASIC-PLUS-2, the time can be expressed 
in either AM/PM format or 24-hour format, depending on the option you 
select when installing BASIC-PLUS-2. 
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Appendix B 


ANSI Minimal BASIC 


This appendix explains the operation of the VAX BASIC compiler when 
used with the /ANSI_STANDARD qualifier. 


B.1 Introduction 


The American National Standard for Minimal BASIC (ANSI X3.60- 
1978) describes a nucleus of the BASIC programming language. This 
nucleus will be a part of any BASIC implementation that conforms to 
this standard. Thus, writing programs that conform to the ANSI Minimal 
BASIC standard helps assure that they will run under any standard 
implementation of BASIC. 


The ANSI Minimal BASIC Standard allows both extensions to the current 
standard and features whose behavior is defined by each implementation. 
This chapter describes these extensions and implementation-defined 
features. Many features of VAX BASIC are allowed as extensions to ANSI 
Minimal BASIC. For example, programs with 31-character variable names 
will compile correctly; however, VAX BASIC reports an informational 
message for each instance of a long variable name. This tells you that 
your program does not strictly conform to ANSI Minimal BASIC. 


Certain features of VAX BASIC are invalid in ANSI Minimal BASIC 
programs. For example, variables ending iri a percent sign are invalid 
because ANSI Minimal BASIC does not allow integer variables. If you try 
to use this VAX feature in ANSI Minimal BASIC, VAX BASIC signals the 
error “Integer data type not supported in ANSI.” 


For a thorough understanding of ANSI Minimal BASIC, read ANSI 
X3.60-1978. 
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Note that the descriptions and explanations in this chapter apply only 
to programs compiled or run with the /ANSI_STANDARD qualifier in 
effect. 


B.2 The /ANSI_STANDARD Qualifier 


/ANSI_STANDARD is a qualifier to both the DCL command BASIC and 
to the SET command in the BASIC environment. When you specify this 
qualifier, the following qualifiers are not allowed: 

e /SYNTAX_CHECK 

e /SCALE 

e /TYPE_DEFAULT 

e /OPTIMIZE (/NOSETUP in the BASIC environment) 


VAX BASIC signals an error if you use any of these qualifiers in addition 
to the /ANSI_STANDARD qualifier. 


Note that you cannot use compiler directives in programs compiled with 
the /ANSI_STANDARD qualifier. In addition, you cannot use immediate 
mode statements while the /ANSI_STANDARD qualifier is in effect. 


B.3 Extensions To ANS! Minimal BASIC Standard X3.60-1978 


The following items are extensions to the ANSI Minimal BASIC Standard. 
In order to write completely transportable programs, you should avoid 
these extensions and use only the capabilities allowed by the standard. 
In most cases VAX BASIC reports an informational error if you use any 
extensions. 


B.3.1 Program Format 


The ANSI Minimal BASIC Standard permits comments only with the REM 
statement. With the /ANSI_STANDARD qualifier in effect, VAX BASIC 
allows comment fields beginning with an exclamation point and ending 
with an exclamation point or a carriage return. 


VAX BASIC also allows explicit line continuation with ampersands. 
However, implicit line continuation is invalid. 
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B.3.2 Statements 


The ANSI Minimal BASIC Standard requires that each program have 

an END statement. In VAX BASIC the END statement is optional. If 
your program does not have an END statement, VAX BASIC reports the 
informational message, “ENDSTAREQ, END statement required in ANSI.” 


Also, the LET keyword is required in ANSI Minimal BASIC. VAX BASIC 
signals “LETKEYREQ, LET keyword required in ANSI” when it encounters 
an assignment statement without the LET keyword. 


B.3.3 Delimiters 


The ANSI Minimal BASIC Standard specifies that all keywords must be 
preceded by one space and followed by at least one space, if the keyword 
is not at the end of a line. With the /ANSI_STANDARD qualifier in 
effect, you can delimit keywords with either spaces or tabs. 


B.3.4 Variables 


The ANSI Minimal BASIC Standard limits variable names in the following 
ways: 


e String variables and string arrays can be named with only one al- 
phabetic character, followed by a dollar sign. For example, valid 
identifiers for string variables are K$, T$, and Q$(17). 


e Numeric arrays can be named with only one alphabetic character, 
followed by the subscript reference. For example, valid identifiers for 
numeric arrays are M(25), K(n), and A(n/2). 


e¢ Simple numeric variables can be named with a maximum of two 
characters: one alphabetic character, followed by an optional digit. 
For example, valid identifiers for simple numeric variables are R5, K1, 
and T2. 


With the /ANSI_STANDARD qualifier in effect, VAX BASIC allows up to 
31-character variable and array names. Names ending in a percent sign 
(%) are invalid, as are any explicitly declared variables. 


Note that VAX BASIC initializes all numeric variables to zero and all 
string variables to the null string. To conform to the minimal standard, 
you should explicitly initialize all variables in your program. 
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All VAX BASIC keywords remain reserved words when the /ANSI_ 
STANDARD qualifier is in effect; you cannot use these reserved words 
as variable names. See Appendix D in this manual for a list of reserved 
keywords. 


B.3.5 Numeric Constants 


The ANSI Minimal BASIC Standard allows numeric constants of the 
following form: 


sd...d Implicit point representation 
sd...drd...d Explicit point unscaled representation 
sd...drd...dEsd...d Explicit point scaled representation 
sd...dEsd...d Implicit point scaled representation 
d 

Is a decimal digit. 

r 

Is a period. 

Ss 


Is an optional sign. 


E 
Is the explicit character E. 


In addition to constants of this form, VAX BASIC with the /ANSI_— 
STANDARD qualifier in effect allows integer constants that end in a 
percent sign (%) and explicitly typed numeric constants. 


B.3.6 Data Input 


VAX BASIC provides several extensions to the ANSI Minimal BASIC 
Standard for data input. 
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B.3.6.1 Unquoted String Data 


The ANSI Minimal BASIC Standard limits unquoted strings occurring in 
a DATA statment, or in response to the input prompt, to the following 
subset of ASCII characters: 


Uppercase letters (A-Z) 
Digits (0-9) 

The period (.) 

The plus sign (+) 

The minus sign (—) 

The space character 


In VAX BASIC, an unquoted string in a DATA statement can contain any 
ASCII character, with the following exceptions: 


The comma (,) 

The null character 

The form feed character 

An ampersand (&), if it is the last character on the line 


As input to the INPUT statement, VAX BASIC allows unquoted strings 

to contain any printable ASCII character (that is, all characters with 

an ASCII code greater than 31, except character code 127, the delete 
character). VAX BASIC also allows the following nonprinting characters in 
the INPUT statement: 


The back space character 
The horizontal tab 

The vertical tab 

The form feed character 


ANSI Minimal BASIC B-5 


B.3.6.2 Null Input 


The ANSI Minimal BASIC Standard requires that the DATA statement 
consist of numeric constants, string constants, or unquoted strings. VAX 
BASIC allows these items, and also allows null items (that is, two succes- 
sive commas not within a quoted string) as input in a DATA statement. 
A null item in a DATA statement results in the assignment of either a 
null string or a numeric value of zero to the corresponding variable in the 
READ statement. 


B.3.7 User-Defined Functions (the DEF Statement) 


The ANSI Minimal BASIC Standard requires that user-defined functions 
accept a single parameter. The formal parameter in the DEF function must 
be an unsubscripted numeric variable. With the /ANSI_STANDARD 
qualifier in effect, VAX BASIC reports a syntax error for DEF functions that 
specify more than one parameter. 


The ANSI Minimal BASIC Standard makes no mention of DEFs with 
string parameters. VAX BASIC in ANSI Standard mode allows string 
DEFs but signals the informational error “String DEF not ANSI.” 


DEF functions can be recursive. However, VAX BASIC does not detect 
infinitely recursive DEF functions. If your program invokes an infinitely 
recursive DEF function, your program will eventually terminate with a 
fatal error (typically, an access violation). 


B.3.8 Built-in Functions 


The ANSI Minimal BASIC Standard allows only the following 
implementation-supplied (built-in) functions: 


e =ABS 
e ATN 
e COS 
e EXP 
e INT 
e LOG 
e RND 
e SGN 
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e SIN 
e SQR 
e TAN 
With the /ANSI_STANDARD qualifier in effect, if you use any built-in 


functions other than these, VAX BASIC reports an informational error 
“Language feature not ANSI.” 


Further, VAX BASIC reports an error if you use any of the following 
functions in a program compiled with the /ANSI_STANDARD qualifier: 


e DECIMAL 
e INTEGER 
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B.3.9 Arrays 


e REAL 
e GETRFA 


The ANSI Minimal BASIC Standard requires that array declarations 
are valid only for numerics, and allows only one or two dimensions. 
With the /ANSI_STANDARD qualifier in effect, VAX BASIC allows 
multi-dimensional arrays of all data types, including strings. 


All arrays have a lower bound of zero unless an OPTION BASE statement 
specifies a lower bound of 1. The format of OPTION BASE is as follows: 


OPTION BASE n 


n 

Is either zero or 1. A value of zero specifies that the lower bound of arrays 
is either (0) or (0,0). A value of 1 specifies that the lower bound is either 
(1) or (1,1). 


Although you can have arrays of any floating-point data type, you control 
this feature with qualifiers to the DCL command BASIC or the SET 
command. This means that all floating-point arrays in a single program 
are of the same data type. 


The ANSI Minimal BASIC Standard requires that all variables and arrays 
have unique names. However, VAX BASIC allows a variable and an array 
to have the same name. 


B.4 Implementation-Defined Features 


The ANSI Minimal BASIC Standard leaves the following features to be 
defined by the implementation. The behavior of these implementation- 
defined features in VAX BASIC is as described in the following sections. 
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B.4.1 


B.4.2 


B.4.3 


B.4.4 


B.4.5 


Initial Values for Variables 


The ANSI Minimal BASIC Standard recommends that all variables are 
“detectably undefined in the sense that an exception will result from any 
attempt to access the value of a variable before that variable is explicitly 
assigned a value.” Therefore you should explicitly initialize all variables. 
VAX BASIC initializes all numeric variables to zero and all dynamic string 
variables to the null string. 


Retention of Long Strings 


The ANSI Minimal BASIC Standard states that string variables must be 
able to contain strings of at least 18 characters. VAX BASIC lets you use 
strings of up to 65535 characters. 


Accuracy of Evaluation of Numeric Expressions 


The ANSI Minimal BASIC Standard does not specify a minimum accuracy, 
but recommends at least six significant decimal digits of precision. In VAX 
BASIC, the accuracy of numeric expressions is always the same as that of 
the operands. This is specified with the /REAL_SIZE qualifier. 


Machine Infinitesimal 


The ANSI Minimal BASIC Standard recommends that machine infinites- 
imal be at most 1E-38. For programs compiled with /REAL—_SIZE of 
SINGLE or DOUBLE, machine infinitesimal is approximately 2.9E-39; 
with /REAL_SIZE=GFLOAT, machine infinitesimal is approximately 
5.6E-308; and with /REAL_SIZE=HFLOAT, machine infinitesimal is 
approximately 8.4E-4933. 


Machine Infinity 


The ANSI Minimal BASIC Standard recommends that machine infinity 
be at least 1E38. For programs compiled with /REAL—SIZE of SINGLE 
or DOUBLE, machine infinity is approximately 1.7E38; with /REAL — 
SIZE=GFLOAT, machine infinity is approximately 9.0E309; and with 
/REAL—SIZE=HFLOAT, machine infinity is approximately 8.4E4933. 
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B.4.6 Precision For Numeric Values 


The ANSI Minimal BASIC Standard recommends at least six significant 
decimal digits of precision. This corresponds to the SINGLE argument 
of the VAX BASIC REAL SIZE qualifier. You can also specify DOUBLE 
or GFLOAT (up to 15 significant decimal digits of accuracy), or HFLOAT 
(up to 33 significant decimal digits of accuracy). See the VAX BASIC User 
Manual for more information. 


Note that the accuracy of numeric expressions is always the same as the 
precision specified with an argument to the REAL_SIZE qualifier. 


B.4.7 Exrad-Width For Printing Numeric Representations 


The ANSI Minimal BASIC Standard requires at least two positions for 
the representation of the exrad component of a numeric represen- 
tation. In VAX BASIC for programs compiled with /REAL_—SIZE of 
SINGLE or DOUBLE, exrad-width is two. For programs compiled with 
/REAL—SIZE=GFLOAT, exrad-width is three. For programs compiled 
with /REAL_SIZE=HFLOAT, exrad-width is four. 


B.4.8 Significance-Width For Printing Numeric Representations 
The ANSI Minimal BASIC Standard specifies at least six positions for 
controlling the number of significant decimal digits printed in numeric 
representations. In VAX BASIC the PRINT statement provides up to six 


significant positions for numeric values, regardless of the floating-point 
data type in effect. 


B.4.9 Print Zone Length 


VAX BASIC always has five 14-position print zones per print line. 
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B.4.10 Margin for Output Line 


The ANSI Minimal BASIC Standard makes no recommendation for the 
width of the output line. With the /ANSI_-STANDARD qualifier in effect, 
the margin width for the controlling terminal is 80 characters. Note that 
the margin width for the controlling terminal is infinite for programs 
compiled with the /NOANSI_STANDARD qualifier. 


B.4.11 Pseudorandom Number Sequence 


In VAX BASIC the RND function produces a pseudorandom sequence 

of numbers until the RANDOMIZE statement is executed. After 
RANDOMIZE executes, the RND function produces a random sequence of 
numbers. 


B.4.12 Unique Line Numbers 


VAX BASIC follows the ANSI Minimal BASIC Standard’s recommenda- 
tions for local editing of statement lines. Statement lines can be entered 
in any order; VAX BASIC sorts the program into the proper order. If you 
enter two lines with the same line number, VAX BASIC keeps the second 
line and deletes the first. VAX BASIC deletes any line containing only a 
line number; it also deletes any line containing only a line number and 
formatting characters (such as spaces or form feeds). 


B.4.13 Input Prompt 
The ANSI Minimal BASIC Standard recommends that the input prompt 
be a question mark followed by a single space. VAX BASIC conforms to 
this recommendation. Note that you cannot supply a string constant to be 


displayed as an input prompt. If you attempt to supply a string prompt, 
VAX BASIC signals “Language feature not ANSI.” 


B.4.14 End of input Reply 


In VAX BASIC, the end of input reply is a carriage return. 
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B.4.15 End of Print Line 


In VAX BASIC, the end of print line is a carriage return/line feed combi- 
nation (ASCII code 13 and 10). 


B.4.16 Exponentiation Operator 


VAX BASIC accepts two asterisk characters (**) as the exponentiation 
operator. 
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Appendix C 


ASCII Character Codes 


ASCII is a 7-bit character code with an optional parity bit (8) added 
for many devices. Programs normally use seven bits internally with the 
eighth bit being zero; the extra bit is either stripped (on input) or added 
by a device driver (on output) so the program will operate with either 
parity- or nonparity-generating devices. The eighth bit is reserved for 
future standardization. 


The International Reference Version (IRV) of ISO Standard 646 is identical 
to the IRV in CCITT Recommendation V.3 (International alphabet No. 5). 
The character sets are the same as ASCII except that the ASCII dollar sign 
(hexadecimal 24) is the international currency sign, which looks like ###. 


ISO Standard 646 and CCITT V.3 also specify the structure for national 
character sets, of which ASCII is the U.S. national set. Certain specific 
characters are reserved for national use. These are the values and symbols: 


Hexadecimal Value IRV ASCII 

23 # # 

24 ### $ (General currency symbol vs. dollar 
sign) 

40 @ @ 

5B [ [ 

5C x \ 

5D ] ] 

5E 7 

60 
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Hexadecimal Value IRV ASCII 


7B { { 
7C | | 
7D } } 
7E (tbs) 


~ (Overline vs. tilde) 


ISO Standard 646 and CCITT Recommendation V.3 (International 
Alphabet No. 5) are identical to ASCII except that the number sign 
(23) is represented as ## instead of #, and certain characters are reserved 


for national use. 


Table C—1: ASCII Codes 


8-Bit 
Decimal Hexadecimal 
Code Code 
0 00 
1 01 
2 02 
3 03 
4 04 
5 05 
6 06 
7 07 
8 08 
9 09 
10 OA 
11 OB 
12 0C 
13 0D 
14 OE 
15 OF 
16 10 
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Character 
NUL 
SOH 

STX 

ETX 

EOT 


ENQ 
ACK 
BEL 
BS 
HT 
LF 
VT 
FF 
CR 
SO 
SI 
DLE 


Remarks 

Null (tape feed) 

Start of heading (“A) 

Start of text (end of address, “B) 
End of text (°C) 


End of transmission (shuts off 
the TWX machine “D) 


Enquiry (WRU, “E) 
Acknowledge (RU, “F) 
Bell (*G) 

Backspace (*H) 
Horizontal tabulation (1) 
Line feed (7J) 

Vertical tabulation (*K) 
Form feed (page, “L) 
Carriage return (“M) 
Shift out (*N) 

Shift in (*O) 

Data link escape (*P) 


Table C-—1 (Cont.): 


Decimal 
Code 


17 
18 
19 
20 
21 


22 
23 
24 
25 
26 
Zi 


28 
2 
30 
31 
32 
33 
34 
eye, 
36 
37 
38 
39 
40 
41 
42 


8-Bit 
Hexadecimal 
Code 


11 
12 
13 
14 
15 


16 
17 
18 
19 
1A 
1B 


1C 
1D 
1E 
1F 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
2A 
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Character 
DC1 

DC2 

DC3 

DC4 

NAK 


SYN 
ETB 
CAN 
EM 
SUB 
ESC 


FS 
GS 
RS 
US 
oF: 
{ 

# 

$ 
% 
& 


Remarks 


Device control 1 (*Q) 
Device control 2 (*R) 
Device control 3 (*S) 
Device control 4 (°T) 
Negative acknowledge (ERR, 
U) 

Synchronous idle (*V) 
End-of-transmission block (“W) 
Cancel (°X) 

End of medium (“Y) 
Substitute (*Z) 


Escape (prefix of escape se- 
quence) 


File separator 

Group separator 
Record separator 

Unit separator 

Space 

Exclamation point 
Double quotation mark 
Number sign 

Dollar sign 

Percent sign 
Ampersand 
Apostrophe 

Left (open) parenthesis 
Right (close) parenthesis 
Asterisk 
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Table C-—1 (Cont.): 


Decimal 
Code 


43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
af 
58 
59 
60 
61 
62 


63 
64 
65 
66 
67 
68 
69 
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8-Bit 
Hexadecimal 
Code 


2B 
2C 
2D 
2E 
2F 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C 
3D 
3E 


3F 
40 
41 
42 
43 
44 
45 


ASCII Codes 


Character 
+ 


, 


Oo DOAN BD OO FF WO NY KF CO ™ 


“ee 


_N 


moONnw>r>@e 


Remarks 


Plus sign 

Comma 

Minus sign, hyphen 
Period (decimal point) 
Slash (slant) 

Zero 

One 

Two 

Three 

Four 

Five 

Six 

Seven 

Eight 

Nine 

Colon 

Semicolon 

Less than(left angle bracket) 
Equal sign 


Greater than (right angle 
bracket) 


Question mark 
Commercial at 
Uppercase A 
Uppercase B 
Uppercase C 
Uppercase D 
Uppercase E 


Table C-—1 (Cont.): ASCII Codes 


8-Bit 
Decimal Hexadecimal 
Code Code Character Remarks 
70 46 F Uppercase F 
71 47 G Uppercase G 
72 48 H Uppercase H 
73 49 It Uppercase | 
74 4A J Uppercase J 
75 4B K Uppercase K 
76 4C L Uppercase L 
77 4D M Uppercase M 
78 4E N Uppercase N 
79 4F O Uppercase O 
80 50 P Uppercase P 
81 51 Q Uppercase Q 
82 52 R Uppercase R 
83 53 S Uppercase S 
84 54 T Uppercase T 
85 55 U Uppercase U 
86 56 Vv Uppercase V 
87 57 W Uppercase W 
88 58 X Uppercase X 
89 59 Y Uppercase Y 
90 5A Z Uppercase Z 
91 5B [ Left square bracket 
92 5C \ Backslash (reverse slant) 
93 5D ] Right square bracket 
94 5E ‘ Circumflex (caret) 
95 5F s Underscore (underline) 
96 60 : Grave accent 
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Table C-—1 (Cont.): 


Decimal 
Code 


97 

98 

99 

10 

101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
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8-Bit 
Hexadecimal 
Code 


61 
62 
63 
64 
65 
66 
67 
68 
69 
6A 
6B 
6C 
6D 
6E 
6F 
70 
71 
Fa 
73 
74 
75 
76 


ASCII Codes 


Character 


> oeinmr on Qn oF DM 


~~ 


— 


7~.0O GU 9 3 8 


”n 


Remarks 


Lowercase a 
Lowercase b 
Lowercase c 
Lowercase d 
Lowercase e 
Lowercase f 
Lowercase g 
Lowercase h 
Lowercase i 
Lowercase j 
Lowercase k 
Lowercase | 
Lowercase m 
Lowercase n 
Lowercase oO 
Lowercase p 
Lowercase q 
Lowercase r 
Lowercase s 
Lowercase t 
Lowercase u 


Lowercase v 


Table C-—1 (Cont.): ASCII Codes 


8-Bit 
Decimal Hexadecimal 
Code Code Character Remarks 
119 77 Ww Lowercase w 
120 78 x Lowercase x 
121 79 y Lowercase y 
122 7A Zz Lowercase z 
123 7B { Left brace 
124 7c | Vertical line 
125 7D } Right brace 
126 7E ad Tilde 
127 7F DEL Delete (rubout) 
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Appendix D 


VAX BASIC Keywords 


The following is a list of the VAX BASIC keywords. Most of the keywords 
are reserved. The unreserved keywords are marked with a dagger. 


% ABORT 
%CDD +t 
%CROSS 
%ELSE 
%END 

% FROM 
%IDENT 
%IF 
%INCLUDE 
%LET 
%LIBRARY 
%LIST 
%NOCROSS 
%NOLIST 
%PAGE 
%PRINT 
%SBITL 
%THEN 
%TITLE 
%VARIANT 
ABORT 

ABS 

ABS% 
ACCESS 
ACCESS % 
ACTIVATE 


t Unreserved keyword. 
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ACTIVE 
ALIGNED 
ALLOW 
ALTERNATE 
AND 
ANGLE ¢ 
ANY 
APPEND 
AREA + 

AS 

ASC 
ASCENDING 
ASCII 

ASK 

AT + 

ATN 

ATN2 
BACK 
BASE 
BASIC 

BEL 
BINARY 
BIT 

BLOCK 
BLOCKSIZE 
BS 
BUCKETSIZE 
BUFFER 
BUFSIZ 

BY 

BYTE 
CALL 
CASE 
CAUSE 
CCPOS 
CHAIN 
CHANGE 
CHANGES 
CHECKING 
CHOICE + 
CHR$ 
CLEAR 
CLIP + 


t+ Unreserved keyword. 
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CLK$ 

CLOSE 
CLUSTERSIZE 
COLOR ft 
COM 
COMMON 
COMP% 
CON 
CONNECT 
CONSTANT 
CONTIGUOUS 
CONTINUE 
COS 

COT 

COUNT 

CR 

CTRLC 
CVTF$ 
CVT$F 
CVT$$ 
CVT$% 
CVT%$ 

DAT 

DAT$ 

DATA 

DATE$ 
DEACTIVATE 
DECIMAL 
DECLARE 
DEF 
DEFAULTNAME 
DEL 

DELETE 
DESC 
DESCENDING 
DET 

DEVICE 

DIF$ 

DIM 
DIMENSION 
DOUBLE 
DOUBLEBUF 
DRAW 


t+ Unreserved keyword. 
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DUPLICATES 
DYNAMIC 
ECHO 
EDIT$ 
ELSE 
END 

EQ 

EQV 

ERL 

ERN$ 

ERR 
ERROR 
ERT$ 

ESC 

EXIT 

EXP 
EXPAND + 
EXPLICIT 
EXTEND 
EXTENDSIZE 
EXTERNAL 
FF 

FIELD 
FILE 
FILESIZE 
FILL 

FILL$ 
FILL% 
FIND 

FIX 

FIXED 
FLUSH 
FNAME$ 
FNEND 
FNEXIT 
FONT t 
FOR 
FORMAT$ 
FORTRAN 
FREE 
FROM 
FSP$ 
FSS$ 


tT Unreserved keyword. 
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FUNCTION 
FUNCTIONEND 


VAX BASIC Keywords D-4.1 





FUNCTIONEXIT 
GE 

GET 
GETRFA 
GFLOAT 
GO 
GOBACK 
GOSUB 
GOTO 
GRAPH 
GRAPHICS t+ 
GROUP 
GT 
HANDLE 
HANDLER 
HEIGHT ft 
HFLOAT 
HT 

IDN 

IF 

IFEND 
IFMORE 
IMAGE 
IMP 

IN t¢ 
INACTIVE 
INDEX t 
INDEXED 
INFORMATIONAL 
INITIAL 
INKEY$ 
INPUT 
INSTR 
INT 
INTEGER 
INV 
INVALID 
ITERATE 
JSB 
JUSTIFY t+ 
KEY 

KILL 
LBOUND 


¢ Unreserved keyword. 
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LEFT 

LEFT$ 

LEN 

LET 

LF 

LINE 

LINES ft 
LINO 
LINPUT 
LIST 

LOC 
LOCKED 
LOG 
LOG10 
LONG 
LSET 

MAG 
MAGTAPE 
MAP 

MAR 
MAR% 
MARGIN 
MAT 

MAX 
METAFILE + 
MID 

MID$ 

MIN 

MIX t 

MOD 
MOD% 
MODE 
MODIFY 
MOVE 
MULTIPOINT + 
NAME 
NEXT 

NO t¢ 
NOCHANGES 
NODATA 
NODUPLICATES 
NOECHO 
NOEXTEND 


+ Unreserved keyword. 
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NOMARGIN 
NONE 
NOPAGE 
NOREWIND 
NOSPAN 
NOT 

NULS$ 

NUM 
NUM$ 
NUM1$ 
NUM2 

NX 

NXEQ 

OF 

ON 
ONECHR 
ONERROR 
OPEN 
OPTION 
OPTIONAL 
OR 
ORGANIZATION 
OTHERWISE 
OUTPUT 
OVERFLOW 
PAGE 
PATH t 
PEEK 

PI 

PICTURE 
PLACE$ 
PLOT 
POINT f 
POINTS t+ 
POS 

POS% 
PPS% 
PRIMARY 
PRINT 
PRIORITY t+ 
PROD$ 
PROGRAM 
PROMPT 7+ 


t Unreserved keyword. 
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PUT 

QUO$ 

RAD$ 
RANDOM 
RANDOMIZE 
RANGE ft 
RCTRLC 
RCTRLO 
READ 

REAL 
RECORD 
RECORDSIZE 
RECORDTYPE 
RECOUNT 
REF 
REGARDLESS 
RELATIVE 
REM 

REMAP 
RESET 
RESTORE 
RESUME 
RETRY 
RETURN 

RFA 

RIGHT 
RIGHT$ 
RMSSTATUS 
RND 
ROTATE 
ROUNDING 
RSET 

SCALE 
SCRATCH 
SEG$ 
SELECT 
SEQUENTIAL 
SET 

SETUP 
SEVERE 

SGN 

SHEAR 
SHIFT 


t+ Unreserved keyword. 
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SI 

SIN 
SINGLE 
SIZE 
SLEEP 

SO 

SP 

SPACE t 
SPACE$ 
SPAN 
SPEC% 
SOR 

SORT 
STATUS 
STEP 
STOP 
STR$ 
STREAM 
STRING 
STRING$ 
STYLE ft 
SUB 
SUBEND 
SUBEXIT 
SUBSCRIPT 
SUM$ 
SWAP% 
SYS 

TAB 

TAN 
TEMPORARY 
TERMINAL 
TEXT + 
THEN 

TIM 

TIME 
TIME$ 

TO 

TRAN + 
TRANSFORM 
TRANSFORMATION ft 
TRM$ 

TRN 


ft Unreserved keyword. 
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TYP 

TYPE 

TYPE$ 
UBOUND 
UNALIGNED 
UNDEFINED 
UNIT + 
UNLESS 
UNLOCK 
UNTIL 
UPDATE 
USAGE$ 
USEROPEN 
USING 
USR$ 

VAL 

VAL% 
VALUE 
VARIABLE 
VARIANT 
VFC 
VIEWPORT ft 
VIRTUAL 
VPS% 

VT 

WAIT 
WARNING 
WHEN 
WHILE 
WINDOW + 
WINDOWSIZE 
WITH t 
WORD 
WRITE 
XLATE 
XLATE$ 
XOR 

ZER 


t Unreserved keyword. 
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A 


% ABORT directive ® 3-2 
ABS% function ® 4-4 
ABS function ® 4-2 
Absolute value 

ABS% function ® 4-4 

ABS function ® 4-2 

MAG function ® 4-181 
ACCESS clause ® 4-253, 4-290 
ACTIVE clause ® 4-267 
ALLOW clause ® 4-253 
Alphanumeric label ® 1-3 

See also Labels 
ALTERNATE KEY clause ® 4-258 
Ampersand (&) 

as a continuation character ® 1-7, 1-8, 1-11 

in DATA statement ® 4-42 
Angle types 

with OPTION statement ® 4-265 
ANSI standards ® B-1 to B-11 
APPEND command ® 2-6 to 2-7 
Arc tangent ® 4-6 
Arithmetic operators ® 1-37, 1-38 
Array 

assigning values to® 4-197, 4-200, 4-209, 

4-302 


bounds ® 4-70, 4-196, 4-200, 4-203, 4-207, 


4-209 
converting with CHANGE statement ® 4-20 
creating with COMMON statement ® 4-27 
creating with DECLARE statement ® 4-48 
creating with DIM statement ® 4-69 
creating with MAP statement ® 4-186 


INDEX 


Array (cont’d.) 


creating with MAT statement ® 4-195, 4-200, 
4-203, 4-206, 4-209 
data type of ® 4-69 
dimensions of ® 4-69 
dynamic ® 4-69, 4-71, 4-72 
elements ® 4-70 
element zero ® 4-71, 4-198, 4-201, 4-204, 
4-207, 4-210, 4-223 
initialization of ® 4-197 
initializing ® 4-73 
inversion of ® 4-198 ; 
redimensioning with MAT statement ® 4-196, 
4-198, 4-201, 4-204, 4-209 
static ® 4-69, 4-70 
transposing ® 4-198 
virtual ® 4-50, 4-69, 4-72, 4-101 
Arrays ® 1-20 
array elements ® 1-21 
definition of © 1-21 
dimensions of ® 1-22 
element zero ® 1-21 
naming ® 1-21, 1-23 
size limits © 1-22 
virtual ® 1-24 
ASCII 
character codes ® C-1 
characters ® 1-35, 1-46, 4-23, C-1 
character set ® 1-11 
conversion ® 4-20, 4-23 
converting to ® 4-5 
radix ® 1-32 
ASCII function ® 4-5 
ASSIGN command ® 2-8 to 2-9 
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Asterisk (*) 


in PRINT USING statement ® 4-279 
with HELP command ® 2-27 
ATN function ® 4-6 


Backslash ( ) 
in continued lines ® 1-8 
in multi-statement lines ® 1-8 
in PRINT USING statement ® 4-282 
statement separator ® 1-8 
BASIC-PLUS-2 
compatibility ® A-1 to A-14 
transporting programs ® A-1 to A-14 
Binary radix ® 1-32 
Blank-if-zero field 
in PRINT USING statement ® 4-279 
Block I/O file 
finding records in® 4-107 
opening ® 4-256 
retrieving records sequentially in ® 4-132 
writing records to ® 4-290 
BLOCKSIZE clause ® 4-253 
Block statement 
ending ® 4-78 
exiting ® 4-91 
Bounds ® 1-21 
default for implicit arrays ® 4-71, 4-196, 4-200, 
4-203, 4-207, 4-209 
lower bounds with COMMON statement ® 4-27 
lower bounds with DECLARE statement ® 4-49 
lower bounds with DIM statement ® 4-70 
lower bounds with MAP DYNAMIC statement ® 
4-190 
lower bounds with records ® 4-307 
maximum ® 1-2 1 
upper bounds with COMMON statement ® 4-27 
upper bounds with DECLARE statement ® 4-49 
upper bounds with DIM statement ® 4-70 
upper bounds with MAP DYNAMIC statement ® 
4-190 
Bucket 
creating with BUCKETSIZE clause ® 4-254 
locking ® 4-105, 4-133 
unlocking ® 4-105, 4-118, 4-133 
BUCKETSIZE clause ® 4-254 


2-Index 


BUFFER clause ® 4-254 
BUFSIZ function ® 4-8 
BYTE data type ® 1-12 
/BYTE qualfier ® 2-12 


C 


CALL statement ® 4-9 to 4-13 

with SUB subprograms ® 4-359 
Caret (*) in PRINT USING statement® 4-279 
CASE clause ® 4-341 
CASE ELSE clause ® 4-341 
CAUSE ERROR statement ® 4-14 to 4-15 
CCPOS function ® 4-16 
CDD 

including definitions from ® 3-10 
CDD (Common Data Dictionary) 

and RECORD statement ® 4-306 

including definitions from® 1-10 
CD formatting character 

in PRINT USING statement ® 4-279 
Centered field 

in PRINT USING statement ® 4-281 
C formatting character 

in PRINT USING statement ® 4-281 
CHAIN statement ® 4-18 to 4-19 
CHANGES clause ® 4-258 
CHANGE statement ® 4-20 to 4-22 
Character 

ASCII ® 4-5, 4-23 

formatting with PRINT USING statement ® 

4-278 to 4-283 

lowercase ® 4-281 

uppercase ® 4-281 
CHARACTER data type ® 1-35 
Character position 

CCPOS function ® 4-16 

of substring ® 4-154, 4-271 
Characters 

ASCII® 1-35, 1-46 

data type suffix ® 1-15 

lowercase ® 2-24 

nonprinting ® 1-35 

processing of ® 1-11 

uppercase ® 2-24 

wildcard ® 2-27 


Character set 


translating with XLATE$ function ® 4-397 
Character sets 
ASCII® 1-11 
VAX BASIC ® 1-11 
CHR$ function ® 4-23 
Clauses 
ACCESS ® 4-107, 4-132, 4-253, 4-290 
ACTIVE ® 4-267 
ALLOW ® 4-105, 4-129, 4-253 
ALTERNATE KEY ® 4-258 
BLOCKSIZE ® 4-253 
BUCKETSIZE ® 4-254 
BUFFER ® 4-254 
BY ®4-9, 4-98, 4-124, 4-360 
CASE ® 4-341 
CASE ELSE ® 4-341 
CHANGES ® 4-258 
CONNECT ® 4-254 
CONTIGUOUS ® 4-254 
COUNT ® 4-289, 4-380 
DEFAULTNAME ® 4-252, 4-255 
DUPLICATES ® 4-258, 4-291 
ELSE ® 4-142 
END IF ® 4-142 
EXTENDSIZE ® 4-255 
FILESIZE ® 4-255 
FOR ® 4-252 
GROUP ® 4-307 
KEY ® 4-104, 4-129, 4-130, 4-321 
MAP ® 4-187, 4-255 
NOREWIND ® 4-256 
NOSPAN ® 4-256 
ORGANIZATION ® 4-256 
OTHERWISE ® 4-246, 4-248 
PRIMARY KEY ® 4-258 
RECORD ® 4-103, 4-128, 4-289, 4-290 
RECORDSIZE ® 4-187, 4-259, 4-289 
RECORDTYPE ® 4-258 
REGARDLESS ® 4-105, 4-129 
RFA ® 4-103, 4-128 
STEP ® 4-114 
TEMPORARY ® 4-260 
UNLOCK EXPLICIT ® 4-104, 4-105, 4-129, 
4-260 
UNTIL ® 4-115 
USEROPEN ® 4-260 
VARIANT ® 4-307 


Clauses (cont‘d.) 
WAIT @ 4-130 
WHILE ® 4-115 
WINDOWSIZE ® 4-261 
CLOSE statement ® 4-24 
Colon (:) 
in labels ® 1-3 
Comma (,) 
in DATA statement ® 4-43 
in DELETE command ® 2-21 
in INPUT LINE statement ® 4-151 
in INPUT statement ® 4-148 
in LINPUT statement ® 4-170 
in LIST command ® 2-31 
in MAT PRINT statement ® 4-206 
in PRINT statement ® 4-273 
in PRINT USING statement ® 4-278 
$ command ® 2-5 
Command files for environment ® 2-2 
Command qualifiers ® 2-10 to 2-38 
VAX BASIC ® 2-10 to 2-38 
Comment 
field ® 1-55 
in DATA statement ® 1-56, 4-42 
in REM statement ® 4-313 
processing of ® 1-11 
REM statement ® 1-57 
transferring control to ® 1-55 
! comment ® 2-3 
Comment fields 
terminating ® 1-56 
Comments 
in environment command files ® 2-2 
processing of ® 1-11 
COMMON area 
size of ® 4-29 
COMMON statement ® 4-26 to 4-30 
with FIELD statement ® 4-101 
COMP% function ® 4-3 1 
Compilation 
conditional ® 3-8, 3-26 
controlling with OPTION statement ® 4-265 
control of ® 1-10, 2-56 
control of listing ® 3-3, 3-16, 3-17, 3-19, 3-20, 
3-21, 3-22, 3-24 
including from CDD ® 1-10, 3-10 
including from text library ® 3-10 
including source code ® 1-10, 3-10 
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Compilation (cont’d.) 

listing ® 2-10 

terminating with %ABORT directive ® 3-2 
Compilation qualifiers © 2-10 to 2-38 

VAX BASIC ® 2-10 to 2-38 
COMPILE command ® 2-10 to 2-19 

VAX BASIC qualifiers © 2-10 to 2-38 
Compiler directives ® 1-10 
Concatenation 

of COMMON areas ® 4-29 

string ® 1-7, 1-38, 1-43 
Conditional branching 

IF statement ® 4-142 

ON...GOSUB statement ® 4-246 

ON...GOTO statement ® 4-248 

SELECT statement ® 4-340 
Conditional compilation ® 1-10 

%VARIANT directive ® 3-26 

with %IF directive ® 3-8 
Conditional expression 

FOR statement ® 4-114 

IF statement ® 4-142 

UNLESS statement ® 4-375 

UNTIL statement ® 4-378 

WHILE statement ® 4-395 
Conditional expressions ® 1-44 

definition of © 1-44 

in %LET directive ® 3-14 
Conditional loops ® 4-114, 4-379, 4-395 
CON function ® 4-197 
CONNECT clause ® 4-254 
Constant 

declaring ® 4-50 

external ® 4-96 

with OPTION CONSTANT TYPE ® 4-265 
Constants ® 1-24 

declaring ® 1-31 

default data type ® 1-24 

definition of © 1-24 

floating-point ® 1-25 

integer ® 1-27 

lexical ® 3-8 

named ® 1-29 

naming ® 1-25, 1-30 

numeric ® 1-25 

packed decimal ® 1-28 

string ® 1-28 

types of ® 1-24 


4-Index 


CONTIGUOUS clause ® 4-254 
Continuation characters 
ampersand ® 1-8 
backslash ® 1-8 
CONTINUE command ® 2-20 
with RUN command ® 2-47 
CONTINUE statement ® 4-33 
Control 
transferring into DEF functions ® 4-246, 4-248 
transferring into FOR...NEXT loops ® 4-136, 
4-138, 4-246, 4-248 
transferring into SELECT blocks ® 4-246, 4-248 
transferring into UNTIL loops ® 4-136, 4-138, 
4-246, 4-248 
transferring into WHILE loops ® 4-136, 4-138, 
4-246, 4-248 
transferring to a label ® 4-136, 4-138 
transferring with CALL statement ® 4-9 
transferring with CHAIN statement ® 4-18 
transferring with GOSUB statement ® 4-136 
transferring with GOTO statement ® 4-138 
transferring with IF statement ® 4-142 
transferring with ON...GOSUB statement ® 
4-246 
transferring with ON...GOTO statement ® 4-248 
transferring with RESUME statement ® 4-152, 
4-171, 4-324 
transferring with RETURN statement ® 4-327 
Conversion 
array to string variable ® 4-21 
string variable to array ® 4-20 
Conversion functions 
CVT$% function ® 4-39 
CVTS$F function ® 4-39 
CVT%$ function ® 4-39 
CVTF$ function ® 4-39 
DECIMAL function ® 4-46 
INTEGER function ® 4-158 
NUM1$ function ® 4-237 
NUMS function ® 4-235 
RAD$ function ® 4-295 
REAL function ® 4-304 
STRS$ function ® 4-354 
VAL% function ® 4-384 
VAL function ® 4-382 
XLATE$ function ® 4-397 
Copying VAX BASIC source text ® 3-10 
COS function ® 4-35 


Cosine ® 4-35 
COUNT clause ® 4-289 
with fixed-length records ® 4-380 
with variable-length records ® 4-380 
CPU time ® 4-369 
Credit-debit field 
in PRINT USING statement ® 4-279 
%CROSS directive ® 3-3 
Cross-reference table 
%CROSS directive ® 3-3 
%NOCROSS directive ® 3-17 
CTRL/C function 
trapping ® 4-299 
with RECOUNT function ® 4-311 
CTRL/C key ® 4-36 
CTRL/Z function ® 2-26 
with INPUT LINE statement ® 4-152 
with INPUT statement ® 4-150 
with LINPUT statement ® 4-171 
CTRLC function ® 4-36 
See also RCTRLC function 
Cursor position 
CCPOS function ® 4-16 
TAB function ® 4-366 
CVTS$$ function ® 4-38 
See also EDITS function 
CVTxx function ® 4-39 
with FIELD statement ® 4-100 


Data 
transferring with MOVE statement ® 4-221 
DATA statement ® 4-42 to 4-43 
See also READ statement 
comment fields in ® 1-56 
in DEF* function ® 4-61 
in DEF function ® 4-55 
in multi-statement lines ® 1-9 
terminating ® 4-42 
with MAT READ statement ® 4-209 
with READ statement ® 4-302 
with RESTORE statement ® 4-321 
Data structures 
defining ® 4-306 
Data type defaults ® 1-15, 1-16 
constants ® 1-24 


Data type functions 


DECIMAL function ® 4-46 
INTEGER function ® 4-158 
REAL function ® 4-304 


Data type keywords ® 1-12 
Data types ® 1-12, 1-13 


BYTE® 1-12 

CHARACTER ® 1-35 

DECIMAL ® 1-13 

decimal overflow checking ® 4-266 
defining with RECORD statement ® 4-306 
DOUBLE ® 1-12 

GFLOAT ® 1-12 

HFLOAT ® 1-12 

in LET statement ® 4-168 

in logical expressions ® 1-48 

in numeric expressions ® 1-40 

INTEGER ® 1-12 

integer overflow checking ® 4-266 
keywords ® 1-12, 1-13 

LONG ® 1-12 

numeric literal notation ® 1-33 

precision ® 1-13 

precision in PRINT statement ® 4-275 
precision in PRINT USING statement ® 4-278 
promotion rules ® 1-40 

range ® 1-13 

REAL ® 1-12 

results for DECIMAL data ® 1-42 

results for GFLOAT and HFLOAT ® 1-41 
results in expressions ® 1-40 

RFA ® 1-13 

setting defaults with OPTION statement ® 4-266 
SINGLE ® 1-12 

size ® 1-13 

storage of ® 1-12, 1-13 

STRING ® 1-13 

suffix characters ® 1-15 

WORD ® 1-12 


Data typing 


explicit ® 1-16 

implicit ® 1-15 

with declarative statements ® 1-16 
with suffix characters ® 1-15 


DATES function ® 4-44 
Date and time functions 


TIMES function ® 4-37 1 
TIME function ® 4-369 
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DCL commands 
in environment ® 2-4 
Debit-credit field 
in PRINT USING statement ® 4-279 
/DEBUG qualifier 
with RUN command ® 2-47 
/DECIMAL _SIZE qualifier ® 2-13 
DECIMAL data type ® 1-13 
constants ® 1-28 
format of ® 1-13 
overflow checking ® 4-266 
promotion rules ® 1-42 
rounding ® 4-266 
storage of ® 1-13 
DECIMAL function ® 4-46 
Decimal radix ® 1-32 
Declarative statements 
COMMON statement ® 4-30 
DECLARE statement ® 4-48 
EXTERNAL statement ® 4-95 
MAP statement ® 4-186 
%DECLARED directive ® 3-3 to 3-5 
DECLARE statement ® 4-48 to 4-52 
CONSTANT ® 1-31, 1-37 
DEF* function 
error handling in® 4-61, 4-79 
multi-line © 4-59 
parameters ® 4-59, 4-60 
recursion in ® 4-61 
single-line ® 4-59 
DEF* statement ® 4-58 to 4-62 
Default 
BUCKETSIZE clause ® 4-254 
COMMON name ® 4-26 
data type ® 4-266 
DEFAULTNAME clause ® 4-255 
error handling ® 4-240 
file name ® 4-18, 4-252 
overriding with DECLARE statement ® 4-48, 
4-51 
overriding with EXTERNAL statement ® 4-95 
parameter-passing mechanisms ® 4-10 to 
4-11, 4-98, 4-124, 4-360 
RECORDSIZE clause ® 4-260 
scale factor ® 4-266 
setting with OPTION statement ® 4-263 
WINDOWSIZE clause ® 4-261 


6-Index 


DEFAULTNAME clause ® 4-252, 4-255 
Defaults 
COMPILE command ® 2-10 
constants ® 1-24 
data type ® 1-15, 1-16 
displaying ® 2-58 
EDIT command ® 2-23 
file name ® 2-36, 2-38, 2-39, 2-41, 2-46, 2-49, 
2-60 
floating-point constants ® 1-25 
implicitly declared variables ® 1-19 
integer constants ® 1-27 
listing file ® 2-10 
LOAD command ® 2-33 
numeric constants ® 1-25 
object module name ® 2-10 
overriding with COMPILE command ® 2-10 
overriding with RUN command ® 2-46 
radix ® 1-32 
RESEQUENCE command ® 2-43 
SCALE command ® 2-51 
SEQUENCE command ® 2-54 
SET command ® 2-56 
SHOW command ® 2-58 
DEF function 
ending ® 4-78 
error handling in® 4-55, 4-239, 4-241, 4-323 
exiting ® 4-90 
recursion in ® 4-56 
transferring control into ® 4-56, 4-246, 4-248 
with INPUT LINE statement ® 4-151 
with INPUT statement ® 4-148 
with LINPUT statement ® 4-170 
with READ statement ® 4-302 
DEF statement ® 4-53 to 4-57 
multi-line ® 4-54 
parameters ® 4-54, 4-55 
single-line ® 4-54 
DELETE command ® 2-21 to 2-22 
DELETE statement ® 4-63 
with UNLOCK statement ® 4-376 
Delimiter 
EDIT command ® 2-23 
in DATA statement ® 4-43 
string literal ® 1-28 
Descriptor ® 4-13, 4-98, 4-124, 4-360 
Detached handler ® 4-391 
Determinant ® 4-65 


DET function ® 4-65 

DIFS function ® 4-67 

Dimension 
of arrays ® 4-69 

Dimensions 
of arrays ® 1-22 

DIMENSION statement ® 4-69 to 4-73 
See also DIM statement 

DIM statement ® 4-69 to 4-73 
executable ® 4-71, 4-72 
nonvirtual, nonexecutable ® 4-70 
virtual ® 4-70 


with MAT statement ® 4-196, 4-198, 4-201, 


4-204, 4-207, 4-209 

Documentation 

program ® 1-55 
Dollar sign ($) 

in DECLARE statement ® 4-49 

in DEF* statement names ® 4-58 

in DEF names ® 4-53 

in PRINT USING statement ® 4-279 

in variable names ® 1-18, 1-19 

suffix character ® 1-15 
DOUBLE data type ® 1-12 
/DOUBLE qualifier ® 1-17, 2-14 
DUPLICATES clause ® 4-258, 4-291 
Dynamic array ® 4-69, 4-71, 4-72 
Dynamic mapping ® 4-100, 4-189, 4-315 
Dynamic storage ® 4-189, 4-315, 4-317 


ECHO function ® 4-74 
See also NOECHO function 
EDITS function ® 4-76 
values ® 4-76 to 4-77 
EDIT command ® 2-23 to 2-25 
E formatting character 
in PRINT USING statement ® 4-282 
Elementary record components ® 4-308 
ELSE clause ® 4-142 
E mathematical constant ® 4-93 
END statement ® 4-78 to 4-81 
SUB subprograms ® 4-359 
E notation ® 1-26 
field in PRINT USING statement ® 4-279 
numbers in® 1-26 


E notation (cont'd.) 


with PRINT statement ® 4-274 
with STR$ function ® 4-354 
Environment 
comments in immediate mode ® 2-2 
Equivalence name ® 2-7 
ERL function ® 4-82 
with labels ® 1-4 
with RESEQUENCE command ® 2-44 
ERN$ function ® 4-84 
ERR function ® 4-86 
Error 
severity level ® 4-265 
Error condition 
clearing with CONTINUE statement ® 4-33 
Error handling 
disabling © 4-244 
ERL function ® 4-82 
ERN$ function ® 4-84 
ERR function ® 4-86 
ERTS function ® 4-88 
in DEF* functions ® 4-61 
in DEF functions ® 4-55, 4-79, 4-239, 4-241 
in FOR...NEXT loops ® 4-324 
in subprograms ® 4-80, 4-91, 4-124, 4-240 
in UNTIL loops ® 4-324 
in WHILE loops ® 4-324 
ON ERROR GO BACK statement ® 4-239 
ON ERROR GOTO 0 statement ® 4-244 
ON ERROR GOTO statement ® 4-241 
OPTION HANDLE ® 4-265 
recursion in ® 4-242 
RESUME statement ® 4-323 
Error handling functions 
CTRLC function ® 4-36 
ERL function @ 4-82 
ERN$ function ® 4-84 
ERR function ® 4-86 
ERT$ function ® 4-88 
RCTRLC function ® 4-299 
Error number ® 4-86 
Error text ® 4-88 
ERTS function ® 4-88 
Evaluation 
of expressions ® 1-52 
of logical expressions ® 1-50 
of numeric relational expressions ® 1-44 
of operators ® 1-52 
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Evaluation (cont’d.) 
of SELECT statement ® 4-341 
of string relational expressions ® 1-46 
Exclamation point (!) 
in comment fields ® 1-55 
in PRINT USING statement ® 4-282 
Executable 
statements ® 1-4 
Execution 
continuing ® 2-20, 2-47 
of multi-statement lines ® 1-8 
of statements ® 1-8 
of system commands ® 2-4 
program ® 2-46 
stopping ® 2-20, 2-47, 4-352 
suspending ® 4-347, 4-388 
EXIT command ® 2-26 
EXIT statement ® 4-90 to 4-92 
EXP function ® 4-93 
Explicit 
creation of arrays ® 4-69 
data typing ® 1-16, 4-263 
declaration of variables ® 1-20 
literal notation ® 1-32 
loop iteration ® 4-160 
record locking ® 4-63, 4-104, 4-105, 4-129, 
4-133, 4-260 
Exponential notation ® 1-26, 4-274 
in PRINT USING statement ® 4-279 
numbers in ® 1-26 
with PRINT statement ® 4-274 
Exponentiation ® 4-93 
Expressions ® 1-37 
conditional ® 1-44 
conditional in %LET directive ® 3-14 
definition of ® 1-37 
evaluation of ® 1-52 
lexical ® 3-9, 3-14, 3-26 
logical ® 1-48 
mixed-mode ® 1-40 
numeric ® 1-38 
numeric relational ® 1-44 
operator precedence in ® 1-53 
parentheses in® 1-53 
relational ® 1-44 
string ® 1-43 
string relational ® 1-46 
types of ® 1-38 
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Extended field 
in PRINT USING statement ® 4-282 
EXTENDSIZE clause ® 4-255 
External 
constant ® 4-96 
function ® 4-96 
picture ® 4-96 
subprogram ® 4-123 
subroutine ® 4-96 
variable ® 4-96 
External constants ® 1-31 
naming ® 1-32 
EXTERNAL statement ® 4-95 to 4-99 
CONSTANT ® 1-31 
parameters ® 4-96 
External variables 
naming ® 1-18 


F 


FAB status ® 4-330 

Field 
asterisk-filled © 4-279 
blank-if-zero ® 4-279 
centered ® 4-281 
credit or debit ® 4-279 
exponential ® 4-279 
extended ® 4-282 
floating dollar sign ® 4-279 
GROUP ® 4-309 
left-justified © 4-281 
multiple fields within a format string ® 4-279 
one-character ® 4-282 
right-justified © 4-28 1 
trailing minus sign ® 4-278 
VARIANT ® 4-309 
zero-filled ® 4-279 

Fields 
comment ® 1-55 

FIELD statement ® 4-100 to 4-101 

File attributes 
BLOCKSIZE clause ® 4-253 
CONTIGUOUS clause ® 4-254 
EXTENDSIZE clause ® 4-255 
FILESIZE clause ® 4-255 
magnetic tape ® 4-253 


File names 


CHAIN statement default ® 4-18 
COMPILE command default ® 2-10 
LOAD command default ® 2-33 
NEW command default ® 2-36 
OLD command default ® 2-38 
OPEN default ® 4-252 
RENAME command default ® 2-39 
REPLACE command default © 2-41 
RUN command default ® 2-46 
SAVE command default ® 2-49 
UNSAVE command default ® 2-60 
File organization 
indexed ® 4-257 
relative © 4-257 
sequential ® 4-257 
undefined ® 4-256 
virtual ® 4-256 
File-related functions 
BUFSIZ function ® 4-8 
CCPOS function ® 4-16 
FSP$ function ® 4-120 
GETRFA function ® 4-134 
MAR function ® 4-192 
RECOUNT function ® 4-311 
STATUS function ® 4-350 
Files 
accessing ® 4-127 
block 1/0 ® 4-107, 4-132, 4-256, 4-290 
closing ® 4-24 
deleting ® 2-60, 4-162, 4-260 
deleting records in ® 4-63, 4-336 
finding buffer size © 4-8 
%INCLUDE ® 3-10, 3-11 
%INCLUDE directive ® 2-43 


indexed ® 4-63, 4-107, 4-132, 4-254, 4-255, 


4-256, 4-290, 4-321, 4-381 

locating ® 4-101 

magnetic tape ® 4-183, 4-253, 4-321 

opening ® 4-250 

relative © 4-63, 4-107, 4-132, 4-254, 4-256, 
4-260, 4-290, 4-380 

renaming ® 4-224 

restoring data ® 4-321 

sequential ® 4-107, 4-132, 4-256, 4-260, 
4-273, 4-290, 4-336, 4-380 


Files (cont’d.) 
terminal-format ® 4-148, 4-151, 4-170, 4-193, 
4-200, 4-203, 4-206, 4-229, 4-259, 
4-273 
virtual ® 4-260, 4-322 
FILESIZE clause ® 4-255 
FILL ® 4-186, 4-222, 4-316 
FILL$ © 4-186, 4-222, 4-316 
FILL keyword ® 4-27 
FILL% ® 4-186, 4-222, 4-316 
FILL% keyword ® 4-27 
FILL items 
formats and storage ® 4-27 to 4-29 
in COMMON statement ® 4-27 
in MAP statement ® 4-186 
in MOVE statement ® 4-222 
in REMAP statement ® 4-316 
FILL keyword ® 4-27 
FIND statement ® 4-102 to 4-108 
with UNLOCK statement ® 4-376 
with UPDATE statement ® 4-380 
FIX function ® 4-109 
compared with INT function ® 4-156 
Floating dollar sign field 
in PRINT USING statement ® 4-279 
Floating-point 
constants ® 1-25 
data types ® 1-12 
promotion rules ® 1-40 
variables ® 1-19 
FNEND statement ® 4-111 
See also END statement 
FNEXIT statement ® 4-112 
See also EXIT statement 
FOR...NEXT loops ® 4-113 to 4-116, 4-226 
conditional ® 4-114 
error handling in ® 4-324 
explicit iteration of © 4-160 
nested ® 4-114 
transferring control into ® 4-114, 4-136, 4-138, 
4-246, 4-248 
unconditional ® 4-114 
FOR_NEXT loops 
exiting ® 4-91 
FOR clause ® 4-252 
Format 
characters in PRINT USING statement ® 4-278 
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Format (cont’d.) 
combination of characters in PRINT USING 
statement ® 4-279 
defaults for U.S. currency ® 4-280 
E® 4-274 
exponential ® 4-274 
multiple print fields with PRINT USING 
statement ® 4-279 
of data in DATA statement ® 4-43 
of FILL items ® 4-27 to 4-29 
of keywords ® 1-5 
of labels ® 1-3 
of line numbers ® 1-2 
of multi-line REM statement ® 4-313 
of multi-statement lines ® 1-8, 1-9 
of program lines ® 1-1 
of statements ® 1-4 
Radix-50 ® 4-295 
FORMATS function ® 4-117 
FOR statement ® 4-113 to 4-116 
FREE statement ® 4-118 
FSP$ function ® 4-120 
Function 
declaring ® 4-49, 4-53, 4-58 
external ® 4-96 
initialization of © 4-55, 4-61 
invocation of ® 4-55, 4-60 
naming ® 4-53, 4-58 
parameters ® 4-54, 4-59 
user-defined ® 4-53, 4-58 
FUNCTIONEND statement ® 4-125 
See also END statement 
FUNCTIONEXIT statement ® 4-126 
See also EXIT statement 
Functions 
lexical ® 3-8, 3-14, 3-26 
FUNCTION statement ® 4-122 to 4-124 
FUNCTION subprograms 
naming ® 4-122 
parameters ® 4-123 


GETRFA function ® 4-134 

GET statement ® 4-127 to 4-133 
with UNLOCK statement ® 4-376 
with UPDATE statement ® 4-380 
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GFLOAT data type ® 1-12 
/GFLOAT qualifier ® 2-14 
GOSUB statement ® 4-136 
inside WHEN blocks ® 4-136 
with RETURN statement ® 4-327 
GOTO statement ® 4-138 
inside WHEN blocks ® 4-138 
GROUP clause ® 4-307 


Handler 

attached ® 4-391 

enter ® 4-140 

exit © 4-140 
HANDLER statement ® 4-140 to 4-141 
HELP command ® 2-27 to 2-28 
Hexadecimal radix ® 1-32 
HFLOAT data type ® 1-12 
/HFLOAT qualifier ® 2-14 
Hyphen (-) 

in DELETE command ® 2-21 

in LIST command ® 2-31 


1/0 
characters transferred ® 4-311 
closing files ® 4-24, 4-80 
deleting records ® 4-63 
dynamic mapping ® 4-315 
finding records ® 4-103 
locking records ® 4-104, 4-105, 4-129, 4-260 
matrix ® 4-231, 4-233 
moving data ® 4-221 
opening files ® 4-250 
retrieving records ® 4-132 
unlocking records ® 4-118, 4-260, 4-376 
updating records ® 4-380 
with CHAIN statement ® 4-18 
writing records ® 4-290 
%IDENT directive ® 3-6 to 3-7 
Identifiers 
PROGRAM statement ® 1-6 
IDENTIFY command ® 2-29 
Identity matrix ® 4-197 
IDN function ® 4-197 


%IF...%THEN...%ELSE...%END %IF directive 
with RESEQUENCE command ® 2-43 

IF... THEN...ELSE statement ® 4-142 to 4-144 
labels in ® 1-4 
multi-line format ® 1-8 

%IF-% THEN-%ELSE-%END %IF directive ® 3-8 to 

3-9 

Immediate mode ® 2-20, 2-47 

Implicit 
continuation of lines ® 1-8 


creation of arrays ® 4-71, 4-196, 4-200, 4-203, 


4-207, 4-209 

data typing ® 1-15 

declaration of variables ® 1-18 
%INCLUDE directive ® 3-10 to 3-13 

with RESEQUENCE command ® 2-43 
Indexed files ® 4-257 

ALTERNATE KEY clause ® 4-258 

BUCKETSIZE clause ® 4-254 

CHANGES clause ® 4-258 

deleting records in® 4-63 

DUPLICATES clause ® 4-258 

finding records in ® 4-107 

MAP clause ® 4-255 

opening ® 4-256 

PRIMARY KEY clause ® 4-258 

restoring data in ® 4-321 

retrieving records sequentially in ® 4-132 

segmented keys in ® 4-258 

updating ® 4-38 1 

writing records to ® 4-290 
Initialization 

in subprograms ® 4-124, 4-360 

of arrays ® 4-197 

of DEF* functions ® 4-61 

of DEF functions ® 4-55 

of dynamic arrays ® 4-73 

of variables ® 1-23, 4-50 

of variables in COMMON statement ® 4-30 

of virtual arrays ® 4-72 
INKEYS function ® 4-145 to 4-147 

with WAIT clause ® 4-145 
INPUT LINE statement ® 4-151 to 4-153 
INPUT statement ® 4-148 to 4-150 
INQUIRE command ® 2-30 

See also HELP command 
Instance @ 4-309 

RECORD ® 4-309 


INSTR function ® 4-154 to 4-155 
See also POS function 
Integer 
constants ® 1-27 
data types ® 1-12 
overflow checking ® 4-266 
promotion rules ® 1-40 
suffix character ® 1-15 
variables ® 1-19 
INTEGER data type ® 1-12 
INTEGER function ® 4-158 
Internal constants 
naming ® 1-30 
Internal variables 
naming ® 1-18 
INT function ® 4-156 
INV function ® 4-198 
ITERATE statement ® 4-160 
Iteration 
of FOR loops ® 4-114 
of loops ® 4-160 
of UNTIL loops ® 4-378 
of WHILE loops ® 4-395 





KEY clause ® 4-104, 4-130 
FIND statement ® 4-105 
GET statement ® 4-129 
RESTORE statement ® 4-321 
segmented keys ® 4-258 

Keywords 
data type ® 1-12 
definition of ® 1-5 
function of ® 1-5 
in RECORD ® 4-307 
list of © C-7 
reserved and unreserved ® C-7 
restrictions ® 1-5 
spacing requirements ® 1-5 

KILL statement ® 4-162 


L 


Labels 
defining ® 1-3 
format of ® 1-3 
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Labels (cont'd.) 


function of © 1-3 
referencing ® 1-3 
transferring control to ® 4-136, 4-138 
with ITERATE statement ® 4-160 
LBOUND function ® 4-163 
LEFT$ function ® 4-165 
See also SEG$ function 
Left-justification 
PRINT USING statement ® 4-281 
with LSET statement ® 4-179 
LEN function ® 4-167 
Length 
of labels ® 1-3 
of STRING data ® 1-13 
variable names ® 1-18 
%LET directive ® 3-14 to 3-15 
LET statement ® 4-168 
Letters 
lowercase ® 1-11, 2-24, 4-281 
uppercase ® 1-11, 2-24, 4-281 
Lexical 
constants ® 3-8 
expressions ® 3-9, 3-14, 3-26 
functions ® 3-8, 3-14, 3-26 
operators ® 3-4, 3-8, 3-14 
order ® 1-11 
variables ® 3-14 
Lexical variables 
assigning values to ® 3-14 
naming ® 3-14 
L formatting character 
in PRINT USING statement ® 4-281 
Libraries 
text © 3-12 
Line numbers 
automatic sequencing ® 2-54 
in %INCLUDE file © 2-43, 3-10 
in RESEQUENCE command ® 2-43 
range of ® 1-2 
Lines 
continued ® 1-8 
displaying ® 2-31 
editing ® 2-23 
elements of ® 1-1 
format of ® 1-1 
length of ® 1-2 
muiti-statement ® 1-8 
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Lines (cont'd.) 
order of ® 1-11, 2-43 
single-statement ® 1-7 
terminating ® 1-2, 1-11, 1-12 
Line terminator ® 1-2, 1-11, 1-12 
with DATA statement ® 4-42 
with INPUT LINE statement ® 4-152 
with INPUT statement ® 4-149 
with LINPUT statement ® 4-17 1 
LINPUT statement ® 4-170 to 4-172 
LIST command ® 2-31 to 2-32 
%LIST directive ® 3-16 
Listing file 
control of ® 1-10, 3-3, 3-16, 3-17, 3-19, 3-20 
%CROSS directive ® 3-3 
defaults ® 2-10 
included code ® 3-10 
%LIST directive ® 3-16 
%NOCROSS directive ® 3-17 
%NOLIST directive © 3-19 
%PAGE directive ® 3-20 
%PRINT directive ® 3-21 
%SBTTL directive ® 3-22 
subtitle © 3-22 
title © 3-24 
%TITLE directive © 3-24 
version identification ® 3-6 
Listing line numbers ® 1-9 
LISTNH command ® 2-31 
See also LIST command 
Literal 
explicit notation ® 1-32 
numeric ® 1-25 
String ® 1-7, 1-11, 1-28, 1-48, 4-279, 4-282 
LOAD command ® 2-33 to 2-34 
with RUN command ® 2-47 
with SCRATCH command ® 2-53 
Local copy ® 4-13 
LOC function ® 4-173 
Lock checking 
REGARDLESS clause ® 4-105, 4-129 
WAIT clause ® 4-130 
LOCK command ® 2-35 
See also SET command 
LOG 10 function ® 4-177 
Logarithms 
common ® 4-177 
natural ® 4-175 


LOG function ® 4-175 
Logical expressions ® 1-48 
compared with relational ® 1-49, 1-50 
data types in® 1-48 
definition of ® 1-44 
evaluation of ® 1-50 
format of ® 1-48 
logical operators ® 1-49 
truth tables ® 1-49 
truth tests ® 1-49 
Logical name ® 2-7 
Logical operators ® 1-49 
LONG data type ® 1-12 
/LONG qualifier ® 2-15 
Loops 
conditional ® 4-114 
exiting © 4-90 
FOR...NEXT ® 4-113 
iteration of ®4-114, 4-160, 4-378, 4-395 
nested FOR...NEXT ® 4-114 
unconditional ® 4-114 
UNTIL statement ® 4-378 
WHILE statement ® 4-395 
Lowercase letters 
in EDIT command ® 2-24 
in PRINT USING statement ® 4-28 1 
processing of ® 1-11 
LSET statement ® 4-179 


MAG function ® 4-181 
Magnetic tape files 
BLOCKSIZE clause ® 4-253 
MAGTAPE function ® 4-183 
NOREWIND clause ® 4-256 
RESTORE statement ® 4-321 
MAGTAPE function ® 4-183 to 4-184 
performing functions in VAX BASIC ® 4-183 to 
4-184 
MAP 
FILL item formats and storage ® 4-27 to 4-29 
MAP area 
naming ® 4-185 
MAP clause ® 4-187, 4-255 
MAP DYNAMIC statement ® 4-189 to 4-191 
with REMAP statement ® 4-315, 4-317 


MAP statement ® 4-185 to 4-188 
with FIELD statement ® 4-101 
with MAP DYNAMIC statement ® 4-191 
with REMAP statement ® 4-315 
MAR function ® 4-192 
Margin 
width ® 4-192, 4-193, 4-229, 4-274 
MARGIN statement ® 4-193 
See also NOMARGIN statement 
with PRINT statement ® 4-274 
MAT 
with DET function ® 4-65 
MAT INPUT statement ® 4-200 to 4-202 
MAT LINPUT statement ® 4-203 to 4-205 
MAT PRINT statement ® 4-206 to 4-208 
MAT READ statement ® 4-209 to 4-211 
Matrix ® 1-21 
identity ® 4-197 
Matrix arithmetic ® 4-197 
Matrix functions 
DET function ® 4-65 
NUM2 function ® 4-233 
NUM function ® 4-231 
Matrix operations 
arithmetic ® 4-197 
assigning values ® 4-200, 4-203, 4-209 
1/0 ® 4-231, 4-233 
inversion ® 4-65, 4-198 
printing ® 4-206 
redimensioning ® 4-200, 4-203, 4-206, 4-209 
scalar multiplication ® 4-197 
transposition ® 4-198 
MAT statement ® 4-195 to 4-199 
with FIELD statement ® 4-101 
MAX function ® 4-212 to 4-213 
Memory 
clearing with SCRATCH command ® 2-53 
MID$ function ® 4-214 
See also SEG$ function 
MIN function ® 4-217 to 4-218 
Minus sign (-) 
in PRINT USING statement ® 4-278 
Mixed-mode expressions ® 1-40 
MOD function ® 4-219 to 4-220 
Modifiable parameters ® 4-12 
Modifiers 
FOR statement ® 4-113 
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Modifiers (cont’d.) 


IF statement ® 4-142 

UNLESS statement ® 4-375 

UNTIL statement ® 4-379 

WHILE statement ® 4-396 
Module names ® 1-6 
MOVE 

FILL item formats and storage ® 4-27 to 4-29 
MOVE statement ® 4-221 to 4-223 

with FIELD statement ® 4-101 
Multi-line 

DEF* functions ® 4-59 

DEF statement ® 4-54 
Multi-statement lines ® 1-8 

backslash in ® 1-8 

branching to ® 1-9 

execution of ® 1-8 

format of ® 1-8, 1-9 

implicit continuation ® 1-8 

transferring control to® 1-8 


NAME...AS statement ® 4-224 
Named constants ® 1-29 

changing ® 1-30 

external ® 1-31, 4-96 

internal ® 1-30, 4-50 
NEW command ® 2-36 to 2-37 
NEXT statement ® 4-226 

with FOR statement ® 4-115 

with WHILE statement ® 4-395 
/[NOJANSI_STANDARD qualifier ® 2-12 
/{NOJAUDIT qualifier © 2-12 
/[NO]CROSS_REFERENCE qualifier ® 2-13 
/(NO]DEBUG qualfier ® 2-13 
/{NO]FLAG qualifier © 2-14 
/{NOJLINE qualifier ® 1-2, 4-82, 4-352 
/[NO]LINES qualifier © 2-14 
/[NOJMACHINE CODE qualifier ® 2-15 
/[NO]JOBJECT qualifier ® 2-15 
/(NOJOVERFLOW qualifier ® 2-15 
/{NOJROUND qualifier © 2-16 
/[NO]SETUP qualifier © 2-16 
/[NOJSHOW qualifier © 2-17 

CDD_DEFINITIONS ® 3-11 

%INCLUDE directive ® 3-11 
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/[NOJSYNTAX_CHECK qualifier © 2-17 
/[NO]TRACEBACK qualifier ® 2-18 
/{NO]WARNINGS qualifier ® 2-18 
%NOCROSS directive ® 3-17 to 3-18 
NOECHO function ® 4-228 
See also ECHO function 
%NOLIST directive ® 3-19 
NOMARGIN statement ® 4-229 
See also MARGIN statement 
Nonexecutable DIM statement ® 4-70 
Nonexecutable statements ® 1-4, 1-11 
COMMON statement ® 4-29 
DATA statement ® 4-43 
DECLARE statement ® 4-50 
DIM statement ® 4-70 
EXTERNAL statement ® 4-98 
MAP DYNAMIC statement ® 4-191 
MAP statement ® 4-187 
REM statement ® 4-313 
UNLESS statement ® 4-375 
Nonmodifiable parameters ® 4-12 
Nonprinting characters 
processing of ® 1-11 
using ® 1-11 
Nonvirtual DIM statement ® 4-70 
NOREWIND clause ® 4-256 
NOSPAN clause ® 4-256 
Notation 
E® 1-26, 
explicit literal © 1-32 
exponential ® 1-26, 4-274 
NOT operator 
evaluation of ® 1-54 
NUL$ ® 4-197 
NUM1$ function ® 4-237 
NUM2 function ® 4-233 
after MAT INPUT statement ® 4-201 
after MAT LINPUT statement ® 4-204 
after MAT READ statement ® 4-210 
NUMS$ function ® 4-235 
Numbers 
random ® 4-297, 4-333 
sign of ® 4-345 
Number sign (#) 
in PRINT USING statement ® 4-278 
Numbers in E notation ® 1-26 
Numeric constants ® 1-25 
Numeric conversion ® 4-21 


Numeric expressions ® 1-38 

format of ® 1-38 

promotion rules ® 1-40 

result data types ® 1-40 

results for DECIMAL data ® 1-42 

results for GFLOAT and HFLOAT ® 1-41 
Numeric functions ® 4-39 

ABS% function ® 4-4 

ABS function ® 4-2 

DECIMAL function ® 4-46 

FIX function ® 4-109 

INT function ® 4-156 

LOG10 function ® 4-177 

LOG function ® 4-175 

MAG function ® 4-181 

RND function ® 4-333 

SGN function ® 4-345 

SOR function ® 4-349 

SWAP% function ® 4-365 
Numeric literal notation ® 1-32 
Numeric operator precedence ® 1-53 
Numeric precision 

with PRINT statement ® 4-275 

with PRINT USING statement ® 4-278 
Numeric relational expressions 

evaluation of ® 1-44 

operators ® 1-45 
Numeric string functions 

CHR$ function ® 4-23 

COMP% function ® 4-31 

DECIMAL function ® 4-46 

DIF$ function ® 4-67 

FORMATS function ® 4-117 

INTEGER function ® 4-158 

NUM1$ function ® 4-237 

NUMS$ function ® 4-235 

PLACE$ function ® 4-268 

PRODS function ® 4-284 

QUO$ function ® 4-292 

REAL function ® 4-304 

STR$ function ® 4-354 

SUMS function ® 4-363 

VAL% function ® 4-384 

VAL function ® 4-382 
Numeric strings 

comparing ® 4-31 

precision ® 4-67, 4-268, 4-285, 4-292, 4-363 


Numeric strings (cont‘d.) 
rounding ® 4-268, 4-285, 4-292 
rounding and truncation values ® 4-269 to 
4-270 
truncating ® 4-268, 4-285, 4-292 
NUM function ® 4-231 
after MAT INPUT statement ® 4-201 
after MAT LINPUT statement ® 4-204 
after MAT READ statement ® 4-210 


Object libraries 
module names in ® 1-6 
Object module 
creating ® 2-10 
default name ® 2-10 
loading ® 2-33 
version identification ® 3-6 
Octal radix ® 1-32 
OLD command ® 2-38 
with RUN command ® 2-46 
ON...GOSUB...OTHERWISE statement ® 4-246 
with RETURN statement ® 4-327 
ON...GOSUB statement ® 4-246 to 4-247 
ON...GOTO...OTHERWISE statement ® 4-248 
ON...GOTO statement ® 4-248 to 4-249 
ON ERROR GO BACK statement ® 4-239 to 4-240 
with END statement ® 4-80 
within a handler ® 4-240 
within protected regions ® 4-240 
ON ERROR GOTO 0 statement ® 4-244 to 4-245 
with END statement ® 4-80 
ON ERROR GOTO statement ® 4-241 to 4-243 
with END statement ® 4-80 
within a handler ® 4-242, 4-245 
within protected regions ® 4-242, 4-245 
with WHEN blocks ® 4-242 
Online documentation ® 2-27 
Opening files 
with USEROPEN clause ® 4-260 
OPEN statement ® 4-250 to 4-262 
with STATUS function ® 4-350 
Operator precedence ® 1-38, 1-52, 1-53 
Operators 
arithmetic ® 1-37, 1-38 
evaluation of ® 1-52 
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Operators (cont’d.) 
lexical ® 3-4, 3-8, 3-14 
logical ® 1-49 
numeric operator precedence ® 1-53 
numeric relational ® 1-45 
precedence of ® 1-38, 1-52, 1-53 
string relational ® 1-47 
OPTIONAL 
with EXTERNAL statement ® 4-97 
OPTION statement ® 4-263 to 4-267 
ORGANIZATION clause ® 4-256 
OTHERWISE clause ® 4-246, 4-248 
Output 
formatting with FORMATS function ® 4-117 
formatting with PRINT USING statement ® 
4-277 to 4-281 
Output listing 
cross-reference table ® 3-3, 3-17 
%LIST directive ® 3-16 
%NOLIST directive ® 3-19 
%PAGE directive ® 3-20 
%PRINT directive ® 3-21 
%SBTTL directive ® 3-22 
% TITLE directive ® 3-24 
Overflow checking ® 4-266 


Pp 


Packed decimal ® 1-13 
See also DECIMAL data type 
%PAGE directive ® 3-20 
Parameter-passing mechanisms 
DEF* functions ® 4-60 
DEF statement ® 4-55 
EXTERNAL statement ® 4-98 
FUNCTION statement ® 4-124 
SUB statement ® 4-360 
VAX BASIC ® 4-10 to 4-11 
Parameters 
DEF* functions ® 4-59, 4-60 
DEF statement® 4-54, 4-55 
EXTERNAL statement ® 4-96 
function ®@ 4-54, 4-59 
FUNCTION subprograms ® 4-123 
modifiable ® 4-12 
nonmodifiable ® 4-12 
SUB subprograms ® 4-358 
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Parentheses 
in array names ® 1-21 
in expressions ® 1-38, 1-53 
Passing mechanisms 
with CALL statement ® 4-9 
Percent sign (%) 
in DATA statement ® 1-27, 4-42 
in DECLARE statement ® 4-49 
in PRINT USING statement ® 4-279 
in variable names ® 1-18, 1-19 
suffix character ® 1-15 
Period (.) 
in PRINT USING statement ® 4-278 
in variable names ® 1-18 
PLACE$ function ® 4-268 to 4-270 
rounding and truncation values ® 4-269 to 
4-270 
Plus sign (+) 
in string concatenation ® 1-43 
POS function ® 4-271 to 4-272 
Precision 
in PRINT statement ® 4-275 
in PRINT USING statement ® 4-278 
NUM1$ function ® 4-237 
NUMS$ function ® 4-235 
of data types ® 1-13 
of numeric strings ® 4-67, 4-268, 4-284, 
4-292, 4-363 
Predefined constants ® 1-35 
PRIMARY KEY clause ® 4-258 
%PRINT directive ® 3-21 
PRINT statement ® 4-273 to 4-276 
with TAB function ® 4-366 
PRINT USING statement ® 4-277 to 4-283 
Print zones 
in MAT PRINT statement ® 4-206 
in PRINT statement ® 4-274 
PROD$ function ® 4-284 to 4-286 
rounding and truncation values ® 4-269 to 
4-270 
Program control statements 
END statement ® 4-78 
EXIT statement ® 4-90 
FOR statement ® 4-113 
GOSUB statement ® 4-136 
GOTO statement ® 4-138 
IF statement ® 4-142 
ITERATE statement ® 4-160 


Program control statements (cont’d.) 


ON...GOSUB statement ® 4-246 
ON...GOTO statement ® 4-248 
RESUME statement ® 4-323 
RETURN statement ® 4-327 
SELECT statement ® 4-340 
SLEEP statement ® 4-347 
STOP statement ® 4-352 
UNTIL statement ® 4-378 
WAIT statement ® 4-388 
WHILE statement ® 4-395 
Program documentation ® 1-55 
Program elements ® 1-1 
Program execution 
continuing ® 2-20, 2-47 
initiating with RUN command ® 2-46 
stopping ® 2-20, 2-47, 4-352 
suspending ® 4-347 
waiting for input ® 4-388 
Program input 
INPUT LINE statement ® 4-151 
INPUT statement ® 4-148 
LINPUT @ 4-170 
waiting for ® 4-388 
Program lines 
automatic sequencing ® 2-54 
deleting ® 2-21 
displaying ® 2-31 
editing ® 2-23 
elements of ® 1-1 
format of ® 1-1 
length of ® 1-2 
numbering ® 1-2 
order of ® 1-11, 2-43 
resequencing ® 2-43 
terminating ® 1-2, 1-11, 1-12 
Programs 
compiling ® 2-10 
continuing ® 2-20, 2-47 
debugging ® 2-47 
deleting ® 2-60 
editing ® 2-23 
ending ® 4-78 
executing ® 2-46 
halting ® 2-20, 2-47 
merging ® 2-5 
naming ® 2-36 
renaming ® 2-39 


Programs (cont’d.) 
saving ® 2-41, 2-49 
stopping ® 2-20, 2-47, 4-352 
PROGRAM statement ® 1-6, 4-287 to 4-288 
Promotion rules 
data type ® 1-40 
DECIMAL ® 1-42 
floating-point ® 1-40 
integer ® 1-40 
Prompt 
after STOP statement ® 4-352 
INPUT LINE statement ® 4-151 
INPUT statement ® 4-148 
LINPUT statement ® 4-170 
MAT INPUT statement ® 4-201 
MAT LINPUT statement ® 4-204 
PSECT ® 4-26, 4-185 
PUT statement ® 4-289 to 4-291 


Qualifiers © 2-10 to 2-38 
/BYTE® 2-12 
/DEBUG ® 2-47 
/DECIMAL _SIZE ® 2-13 
/DOUBLE ® 1-17, 2-14 
/GFLOAT ® 2-14 
/HFLOAT ® 2-14 
/LONG ® 2-15 
/[NOJANS!I_STANDARD ® 2-12 
/[NO]JAUDIT ® 2-12 
/[NO]CROSS_REFERENCE ® 2-13 
/[NO]DEBUG ® 2-13 
/[NO]FLAG ® 2-14 
/[NO]LINE ® 1-2, 4-82, 4-352 
/(NO]LINES ® 2-14 
/[NOJMACHINE_CODE ® 2-15 
/[NOJOBJECT ® 2-15 
/[NOJOVERFLOW ® 2-15 
/{[NOJROUND ® 2-16 
/[NOJSETUP ® 2-16 
/[NO]SHOW ® 2-17, 3-11 
/{NOJSYNT AX _CHECK ® 2-17 
/[NO]TRACEBACK ® 2-18 
/[NOJWARNINGS ® 2-18 
/SINGLE ® 2-17 
/TYPE® 1-15 
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Qualifiers (cont’d.) 
/TYPE_DEFAULT ® 2-18 
/VARIANT ® 2-18, 3-26 
VAX BASIC command ® 2-10 to 2-38 
/WORD ® 2-19 
QUO$ function ® 4-292 to 4-294 
rounding and truncation values ® 4-269 to 
4-270 
Quotation marks 
in string literals © 1-28 


RAB status ® 4-330 
RADS$ function ® 4-295 to 4-296 
Radix 
ASCII ® 1-32 
binary ® 1-32 
decimal ® 1-32 
hexadecimal ® 1-32 
in explicit literal notation ® 1-32 
octal ® 1-32 
Radix-50 ® 4-295 
RANDOMIZE statement ® 4-297 to 4-298 
See also RND statement 
Random numbers ® 4-297, 4-333 
Range 
of data types ® 1-13 
of subscripts ® 1-21 
RCTRLC function ® 4-299 
See also CTRLC function ® 4-299 
RCTRLO function ® 4-300 to 4-301 
READ statement ® 4-302 to 4-303 
See also DATA statement 
with DATA statement ® 4-42, 4-43 
REAL data type ® 1-12 
REAL function ® 4-304 to 4-305 
Record attributes 
MAP clause ® 4-255 
RECORDSIZE clause ® 4-255, 4-259 
RECORDTYPE clause ® 4-258 
Record buffer 
DATA pointers ® 4-321 
MAP DYNAMIC pointers ® 4-191, 4-317 
moving data® 4-221 
REMAP pointers ® 4-315, 4-317 
setting size ® 4-254 


18-Index 


RECORD clause ® 4-103, 4-128, 4-289, 4-290 
Record File Address ® 1-13, 4-103, 4-128, 4-134 
RECORD items 
accessing ® 4-308 
Record Management Services 
See RMS 
Record pointers 
after FIND statement ® 4-107, 4-108 
after GET statement ® 4-132, 4-133 
after PUT statement ® 4-290 
after UPDATE statement ® 4-380 
REMAP statement ® 4-317 
RESTORE statement ® 4-321 
WINDOWSIZE clause ® 4-261 
Records 
deleting with DELETE statement ® 4-63 
deleting with SCRATCH statement ® 4-336 
finding RFA of ® 4-103, 4-129 
locating by KEY ® 4-107, 4-129, 4-133 
locating by RECORD number ® 4-128 
locating by RFA ® 4-103, 4-107, 4-129, 4-132 
locating randomly ® 4-107 
locating sequentially ® 4-103, 4-107, 4-128, 
4-132 
locating with FIND statement ® 4-102 
locating with GET statement ® 4-127 
locking ® 4-104, 4-105, 4-133, 4-260 
locking with GET statement ® 4-129 
processing ® 4-127, 4-254 
retrieving by KEY ® 4-129, 4-133 
retrieving by RECORD number ® 4-128 
retrieving by RFA® 4-128, 4-132 
retrieving randomly ® 4-133 
retrieving sequentially ® 4-128, 4-132 
retrieving with GET statement ® 4-127 
size of © 4-289 
stream ® 4-257 
unlocking ® 4-63, 4-105, 4-118, 4-133, 4-260 
unlocking with UNLOCK statement ® 4-376 
writing by RECORD number ® 4-289 
writing sequentially ® 4-290 
writing with PRINT statement ® 4-273 
writing with PUT statement ® 4-289 
writing with UPDATE statement ® 4-380 
RECORDSIZE clause ® 4-187, 4-259, 4-289 
RECORD statement ® 4-306 to 4-310 


RECORD structures 
components of ® 4-309 
declaring ® 4-309 
RECORDTYPE clause ® 4-258 
RECOUNT function ® 4-311 to 4-312 
after GET statement ® 4-133 
after INPUT LINE statement ® 4-152 
after INPUT statement ® 4-150 
after LINPUT statement ® 4-17 1 
Recursion 
in DEF functions ® 4-61 
in DEF functions ® 4-56 
in error handlers ® 4-242 
in subprograms ® 4-360 
Redimensioning arrays 
with executable DIM statement ® 4-7 1 
REGARDLESS clause 
with FIND statement ® 4-105 
with GET statement ® 4-129 
Relational expressions ® 1-44 
compared with logical ® 1-49, 1-50 
definition of ® 1-44 
format of ® 1-44 
in SELECT statement ® 4-341, 4-342 
numeric ® 1-44 
string ® 1-46 
truth tests ® 1-44, 1-46 
Relational operators 
numeric ® 1-45 
string ® 1-47 
Relative files ® 4-257 
BUCKETSIZE clause ® 4-254 
deleting records in ® 4-63 
finding records in ® 4-107 
opening ® 4-256 
record size in ® 4-260 
retrieving records sequentially in ® 4-132 
updating ® 4-380 
writing records to ® 4-290 
REMAP statement ® 4-315 to 4-319 
FILL item formats and storage ® 4-27 to 4-29 
with MAP DYNAMIC statement ® 4-191 
REM statement ® 4-313 to 4-314 
in multi-statement lines ® 1-9 
multi-line format ® 1-57, 4-313 
terminating ® 1-57, 4-313 
transferring control to ® 1-57 
RENAME command ® 2-39 to 2-40 


REPLACE command ® 2-41 to 2-42 
with RENAME command ® 2-39 
RESEQUENCE command ® 2-43 to 2-45 
Reserved words ® 1-5 
RESET statement ® 4-321 
See also RESTORE statement 
RESTORE statement ® 4-321 to 4-322 
Result data types 
for DECIMAL data ® 1-42 
GFLOAT and HFLOAT ® 1-41 
mixed-mode expressions ® 1-40 
RESUME statement ® 4-323 to 4-324 
END statement ® 4-80 
ERL function ® 4-82 
ERN$ function ® 4-84 
ERR function ® 4-86 
INPUT LINE statement ® 4-152 
INPUT statement ® 4-150 
LINPUT statement ® 4-17 1 
RETRY statement ® 4-325 to 4-326 
with FOR...NEXT loops ® 4-325 
with FOR...UNTIL loops ® 4-325 
with FOR...WHILE loops ® 4-325 
RETURN statement ® 4-327 
RFA clause ® 4-103, 4-128 
RFA data type 
allowable operations ® 1-13 
storage of ® 1-13 
R formatting character 
in PRINT USING statement ® 4-28 1 
RIGHTS function ® 4-328 to 4-329 
See also SEG$ function 
Right-justification 
PRINT USING statement ® 4-28 1 
with RSET statement ® 4-335 
RMS (Record Management Services) 
accessing records ® 4-127 
deleting records ® 4-63 
locating records ® 4-101 
opening files © 4-250 
operations ® 4-330 
replacing records ® 4-380 
RMSSTATUS function ® 4-330 to 4-332 
RND function ® 4-333 to 4-334 
See also RANDOMIZE statement 
RSET statement ® 4-335 
RUN command ® 2-46 to 2-48 
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RUNNH command ® 2-46 
See also RUN command 





SAVE command ® 2-49 to 2-50 

with RENAME command ® 2-39 
%SBTTL directive ® 3-22 to 3-23 
SCALE command ® 2-51 to 2-52 
Scale factor 

setting with OPTION statement ® 4-266 

setting with SCALE command ® 2-51 
SCRATCH command ® 2-53 
SCRATCH statement ® 4-336 to 4-337 
SEGS$ function ® 4-338 to 4-339 
Segmented keys ® 4-258 
SELECT 

transferring control into ® 4-246, 4-248 
SELECT statement ® 4-340 to 4-342 
Semicolon (:) 

in INPUT LINE statement ® 4-152 

in INPUT statement ® 4-149 

in LINPUT statement ® 4-171 

in MAT PRINT statement ® 4-206 

in PRINT statement ® 4-273 
SEQUENCE command ® 2-54 to 2-55 
Sequential files ® 4-257 

deleting records in ® 4-336 

finding records in® 4-107 

fixed-length ® 4-257 

NOSPAN clause ® 4-256 

opening ® 4-256 

record size in® 4-260 

retrieving records in ® 4-132 

stream ® 4-257 

updating ® 4-380 

variable-length ® 4-257 

writing records to ® 4-273, 4-290 
SET command ® 2-56 to 2-57 

VAX BASIC qualifiers ® 2-10 to 2-38 
SET PROMPT statement ® 4-343 to 4-344 
SGN function ® 4-345 
SHOW command ® 2-58 to 2-59 
Sine ® 4-346 
SIN function ® 4-346 
SINGLE data type ® 1-12 
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Single-line 
DEF* functions ® 4-59 
DEF statement ® 4-54 
loops ® 4-113, 4-378, 4-395 
/SINGLE qualifier ® 2-17 
Single-statement lines ® 1-7 
Size 
of numeric data ® 1-13 
of STRING data ® 1-13 
SLEEP statement ® 4-347 
Source text 
copying ® 1-10 
SPACES function ® 4-348 
SOR function ® 4-349 
SORT function ® 4-349 
Square roots ® 4-349 
Statement blocks 
exiting ® 4-90 
Statement modifiers 
FOR statement ® 4-113 
IF statement ® 4-142 
UNLESS statement ® 4-375 
UNTIL statement ® 4-379 
WHILE statement ® 4-396 
Statements 
backslash separator ® 1-8 
block ® 4-78, 4-91, 4-114, 4-142, 4-307, 
4-341 
components of ® 1-4 
continued ® 1-7 
data typing ® 1-16 
declarative ® 4-48 
empty ® 1-56 
executable ® 1-4 
execution of ® 1-8 
format of ® 1-4 
labeling of ® 1-3 
multi-statement lines ® 1-8 
nonexecutable ® 1-4, 1-11, 4-29, 4-43, 4-50, 
4-70, 4-98, 4-187, 4-191, 4-313 
order of ® 1-11, 2-43 
processing of ® 1-11 
single-line © 1-7 
Static 
arrays © 4-70 
mapping ® 4-185 
storage ® 4-27, 4-185, 4-317 
STATUS function ® 4-350 to 4-351 


STATUS function (cont‘d.) 


VAX BASIC STATUS bits ® 4-350 to 4-351 
STEP clause ® 4-114 
STOP statement ® 4-352 to 4-353 
See also CONTINUE statement 
with RUN command ® 2-47 
Storage 
allocating for FILL items ® 4-316 
allocating for FILL items ® 4-222 
allocating for RECORD structures ® 4-309 
allocating for VARIANT fields ® 4-309 
allocating with MAP DYNAMIC statement ® 
4-189 
allocating with MAP statement ® 4-186 
allocating with REMAP statement ® 4-315 
COMMON area and MAP area ® 4-29, 4-187 
dynamic ® 4-189, 4-315, 4-317 
for arrays ® 4-71 
for FILL items ® 4-27 to 4-29, 4-222 
for record structures ® 4-309 
in COMMON statement ® 4-30 
in MAP statement ® 4-187 
of data® 1-13 
of DECIMAL data® 1-13 
of RFA data® 1-13 
of STRING data ® 1-13 
shared ® 4-26, 4-185 
static ® 4-27, 4-185, 4-317 
STR$ function ® 4-354 to 4-355 
Stream 
format ® 4-257 
record ® 4-257 
STRINGS function ® 4-356 to 4-357 
String arithmetic functions 
DIFS function ® 4-67 
PLACE$ function ® 4-268 
PROD$ function ® 4-284 
QUO$ function ® 4-292 
SUM$ function ® 4-363 
String constants ® 1-28 
processing of ® 1-29 
String data 
assigning with LSET statement ® 4-179 
assigning with RSET statement ® 4-335 
STRING data type ® 1-13 
length ® 1-13 
storage of ® 1-13 
String expressions ® 1-43 


String expressions (cont’d.) 


relational ® 1-46 


String functions ® 4-39 


ASCII function ® 4-5 
EDITS function ® 4-76 
INSTR function ® 4-154 
LEFT$ function ® 4-165 
LEN function ® 4-167 
MID$ function ® 4-214 
POS function ® 4-271 
RIGHTS function ® 4-328 
SEG$ function ® 4-338 
SPACES function ® 4-348 
STRINGS function ® 4-356 
TRM$ function ® 4-372 
XLATE$ function ® 4-397 


String literals © 1-48 


continuing ® 1-7 

delimiter ® 1-28 

in PRINT USING statement ® 4-282 
processing of ® 1-11 

quotation marks in ® 1-28 


String relational expressions 


evaluation of ® 1-46 
operators ® 1-47 
padding ® 1-46 


Strings 


comparing ® 1-46, 4-31 

concatenating ® 1-7, 1-38, 1-43 

converting ® 4-20 

creating ® 4-348, 4-356 

editing ® 4-76, 4-372 

extracting substrings ® 4-165, 4-214, 4-328, 
4-338 

finding length ® 4-167 

finding substrings ® 4-154, 4-271 

justifying with FORMATS function ® 4-117 

justifying with LSET statement ® 4-179 

justifying with PRINT USING statement ® 4-28 1 

justifying with RSET statement ® 4-335 

numeric ® 4-31, 4-67, 4-158, 4-268, 4-284, 
4-292, 4-304, 4-363, 4-382, 4-384 

replacing substrings ® 4-214 

suffix character ® 1-15 


String variables ® 1-20 


formatting storage ® 4-179, 4-335 
in INPUT LINE statement ® 4-152 
in INPUT statement ® 4-149 
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String variables (cont'd.) 
in LET statement ® 4-168 
in LINPUT statement ® 4-171 
SUBEND statement ® 4-361 
See also END statement 
SUBEXIT statement ® 4-362 
See also EXIT statement 
Subprograms 
calling ® 4-9 
declaring ® 4-95 
ending ® 4-78, 4-123, 4-359 
error handling in® 4-80, 4-91, 4-124, 4-240 
exiting ® 4-90 
FUNCTION statement ® 4-122 
naming ® 4-9, 4-358 
recursion in ® 4-360 
returning from ® 4-327 
SUB statement ® 4-358 
Subroutines 
external ® 4-96 
GOSUB statement ® 4-136 
RETURN statement ® 4-327 
Subscripted variables ® 1-20 
format of ® 1-22 
range checking ® 4-266 
subscript range ® 1-21 
Subscripts ® 1-21 
range of ® 1-21 
SUB statement ® 4-358 to 4-360 
parameters ® 4-358 
VAX BASIC parameter-passing mechanisms ® 
4-10 to 4-11 
Substrings 
extracting © 4-214, 4-338 
extracting with LEFT$ function ® 4-165 
extracting with MID$ function ® 4-214 
extracting with RIGHTS function ® 4-328 
extracting with SEG$ function ® 4-338 
finding ® 4-154, 4-271 
replacing ® 4-214 
Suffix characters 
integer ® 1-15 
string® 1-15 
SUM$ function ® 4-363 to 4-364 
SWAP% function ® 4-365 
SYSSCURRENCY ® 4-280 
SYSS$DIGIT_SEP ® 4-280 
SYS$RADIX _POINT ® 4-280 
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System command ® 2-4 
$ system-command ® 2-4 


T 


TAB function ® 4-366 to 4-367 
TAN function ® 4-368 
Tangent ® 4-368 
TEMPORARY clause ® 4-260 
Tensor ® 1-21 
Terminal 
printing to ® 4-273 
Terminal control functions 
ECHO function ® 4-74 
NOECHO function ® 4-228 
RCTRLO function ® 4-300 
TAB function ® 4-366 
Terminal-format files ® 4-259 
input from ® 4-148, 4-151, 4-170, 4-200, 
4-203 
margin ® 4-193, 4-229 
writing records to ® 4-206, 4-273 
Text libraries 
accessing ® 3-12 
TIMES function ® 4-37 1 
TIME function ® 4-369 to 4-370 
function values ® 4-369 to 4-370 
%TITLE directive ® 3-24 to 3-25 
Trailing minus sign field 
in PRINT USING statement ® 4-278 
Trigonometric functions 
ATN function ® 4-6 
COS function ® 4-35 
SIN function ® 4-346 
TAN function ® 4-368 
TRMS function ® 4-372 
TRN ® 4-198 
Truncation 
in numeric strings ® 4-268, 4-269 to 4-270, 
4-285, 4-292 
in PRINT USING statement ® 4-281 
with FIX function ® 4-109 
Truth tables ® 1-49 
Truth tests 
in logical expressions ® 1-49 
in relational expressions ® 1-44 
in string relational expressions ® 1-46 


/TYPE_DEFAULT qualifier ® 2-18 
/TYPE qualifier ® 1-15 


UBOUND function ® 4-373 to 4-374 
Unconditional branching 
with GOSUB statement ® 4-136 
with GOTO statement ® 4-138 
Unconditional loops ® 4-114 
Undefined files ® 4-256 
Underscore (_) 
in PRINT USING statement ® 4-279 
in variable names ® 1-18 
UNLESS statement ® 4-375 
UNLOCK EXPLICIT clause ® 4-104, 4-105, 4-129, 
4-260 
UNLOCK statement ® 4-376 to 4-377 
UNSAVE command ® 2-60 
UNTIL clause ® 4-115 
UNTIL loops ® 4-226 
error handling in ® 4-324 
exiting ® 4-91 
explicit iteration of © 4-160 
transferring control into ® 4-136, 4-138, 4-246, 
4-248 
UNTIL statement ® 4-378 to 4-379 
UPDATE statement ® 4-380 to 4-381 
with UNLOCK statement ® 4-376 
Upper bounds 
determining with UBOUND function ® 4-373 
Uppercase letters 
in EDIT command ® 2-24 
in PRINT USING statement ® 4-28 1 
processing of ® 1-11 
User-defined functions ® 4-53, 4-58 
USEROPEN clause ® 4-260 


V 


VAL% function ® 4-384 to 4-385 
VAL function ® 4-382 to 4-383 
Values 
assigning to array elements ® 4-197, 4-200, 
4-203, 4-209, 4-302 
assigning to variables ® 4-168 
assigning with LET statement ® 4-168 


Values (cont’d.) 


assigning with LINPUT statement ® 4-170 
assigning with LSET statement ® 4-179 
assigning with MAT INPUT statement ® 4-200 
assigning with MAT LINPUT statement ® 4-203 
assigning with MAT READ statement ® 4-209 
assigning with READ statement ® 4-302 
assigning with RSET statement ® 4-335 
comparing ® 4-106 
Variable names 
in COMMON statement ® 4-29 
in MAP DYNAMIC statement ® 4-191 
in MAP statement ® 4-186 
in REMAP statement ® 4-316 
rules for ® 1-17 
Variables ® 1-17 
assigning values to ® 4-148, 4-151, 4-168, 
4-170, 4-302 
comparing ® 4-106 
declaring ® 4-48 
definition of ® 1-17 
explicitly declared ® 1-20 
external ® 4-96 
floating-point ® 1-19 
implicitly declared ® 1-18 
initialization of © 1-23, 4-30, 4-50 
in MOVE statement ® 4-221 
in SUB subprograms ® 4-360 
integer ® 1-19 
lexical ® 3-14 
loop ® 4-114 
naming ® 1-17 
string ® 1-20, 4-149, 4-152, 4-168, 4-171 
subscripted ® 1-20 
VARIANT clause ® 4-307 
%VARIANT directive ® 3-26 to 3-27 
in %IF directive ® 3-8 
in %LET directive ® 3-14 
/VARIANT qualifier ® 2-18, 3-26 
VAX BASIC character set ® 1-11 
VAX BASIC STATUS bits ® 4-350 to 4-351 
Vector ® 1-21 
Version identification ® 3-6 
Virtual address 
finding ® 4-173 
Virtual arrays ® 4-50, 4-69, 4-72 
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Preface 


intended Audience 


This manual presents tutorial information on VAX BASIC language fea- 
tures and describes how to develop and use VAX BASIC programs on 
VAX/VMS systems. Readers are presumed to have some previous knowl- 
edge of BASIC or another high-level programming language. This manual 
should be used with the other two manuals in the documentation set. 


Associated Documents 


This manual is one of three manuals that form the VAX BASIC document 
set. The other two manuals are: 


VAX BASIC Reference Manual Provides reference material and syntax for 


all VAX BASIC language elements except 
graphics capabilities 


Programming with VAX BASIC Provides tutorial and reference material for 
Graphics VAX BASIC graphics capabilities 


You may also be interested in the following supplementary manuals: 


VAX BASIC Syntax Summary 
Introduction to BASIC 
BASIC for Beginners 

More BASIC for Beginners 
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Structure of This Document 
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This manual has 23 chapters and 2 appendixes. The chapters are grouped 
into three parts as follows: 


Developing VAX BASIC Programs on VAX/VMS 


Chapter 1 
Chapter 2 
Chapter 3 


Chapter 4 


Chapter 5 


Provides a brief overview of VAX BASIC 
Shows you how to get started on VAX/VMS 


Describes how to develop programs in the BASIC environ- 
ment 

Describes how to develop programs from DCL command 
level and how to generate a compiler listing 


Describes how to use the VAX/VMS Symbolic Debugger to 
debug VAX BASIC programs 


VAX BASIC Programming Concepts 


Chapter 6 
Chapter 7 
Chapter 8 
Chapter 9 
Chapter 10 


Chapter 11 
Chapter 12 
Chapter 13 
Chapter 14 
Chapter 15 
Chapter 16 


Chapter 17 
Chapter 18 


Explains the elements of VAX BASIC programs 
Explains simple input and output procedures 
Shows how to use VAX BASIC arrays 

Explains data definitions 


Explains how to create user-defined data structures with the 
RECORD statement 


Shows how to control the flow of program execution 
Explains how to use VAX BASIC functions 

Explains how to handle strings in VAX BASIC 

Describes structured VAX BASIC programming techniques 
Explains how to manage files 


Describes how to format output with the PRINT USING 
statement 


Explains error handling techniques 


Shows how to use compiler directives 


Using VAX BASIC Features on VAX/VMS 


Chapter 19 
Chapter 20 


Chapter 21 
Chapter 22 


Chapter 23 


Chapter 24 


Appendixes 


Appendix A 
Appendix B 
Appendix C 


Conventions 
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Convention 
$ BASIC prog] 


UPPERCASE letters 


lowercase letters 


Describes how to represent data on VAX/VMS systems 


Describes additional I/O considerations on VAX/VMS 
systems 


Describes System Services and Run-Time Library routines 


Describes the use of user-supplied libraries and shareable 
images 


Explains how definitions extracted from the VAX Common 
Data Dictionary are translated to RECORD statements in VAX 
BASIC 


Explains how to use the dependency recording feature of 
CDD/Plus Version 4.0 in VAX BASIC programs 


Lists compile-time error messages 
Lists run-time error messages 
Describes how to use LSE and SCA with VAX BASIC 


Meaning 


In command-line examples, the user’s 
response to a prompt is printed in red; 
system prompts are printed in black. 


A vertical ellipsis indicates that code 
which would normally be present is 
not shown. 


Uppercase letters are used for VAX 
BASIC keywords and must be coded 
exactly as shown. 


_ Lowercase letters are used to indicate 
user-supplied names or characters. 
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Summary of Technical Changes 


Summary of New and Changed Features for Version 3.3 


Version 3.3 of VAX BASIC includes support for the CDD/Plus Version 4.0 
CDO-format dictionaries while continuing to provide full support for the 
DMU-format dictionaries used in previous versions of CDD. Both types 
of dictionaries can coexist on a system and a program can access data 
definitions on both. This new functionality is implemented as follows: 


e Addition of the /DEPENDENCY_DATA qualifier to the DCL com- 
mand, BASIC 

e Addition of the lexical directive, % REPORT % DEPENDENCY 

e Modification of the lexical directive, %INCLUDE %FROM %CDD 


Descending keys are now supported on both primary and alternate 
keys. This new functionality is implemented by allowing the choice of 
ASCENDING or DESCENDING on key definition clauses in the OPEN 
statement. 


In addition, this documentation update contains numerous corrections and 
clarifications to previous documentation; these documentation changes do 
not reflect new features. 


July 1988 Xxix 


Summary of New and Changed Features for Version 3.1 


Version 3.1 of VAX BASIC includes support for the VAX Source Code 
Analyzer (SCA). SCA is a programming tool that can be used to cross- 
reference and analyze VAX BASIC source code. See Appendix C of this 
manual for a description of how to use SCA with VAX BASIC. 


VAX BASIC Version 3.1 also corrects a number of problems and in- 
compatibilities with previous versions. See the VAX BASIC online 
release notes for more information. The release notes are located in 
SYS$HELP:BASIC031.RELEASE_NOTES. 


Summary of New and Changed Features for Version 3.0 


Version 3.0 of VAX BASIC includes extensive graphics capabilities, struc- 
tured error handling techniques, enhancements to file I/O and other 
new features. All of these features are documented in the VAX BASIC 
Reference Manual and this manual except for the graphics features, which 
are documented in Programming with VAX BASIC Graphics. This section 
summarizes all of the major changes for this release. 


Graphics Capabilities 


VAX BASIC supports extensive graphics capabilities based on VAX GKS. 
The new graphics capabilities are available to you if you have the full or 
run-time VAX GKS kit installed on your system (Version 2.0 or later) and 
if you use supported graphics hardware. The main features of VAX BASIC 
graphics are as follows: 

e A short learning period 

e Convenient default values for attributes 

e Statements consisting of English words in simple constructs 

e Window and viewport settings that are easy to alter 


e Graphics subprograms that can be invoked with a variety of transfor- 
mation functions 


e Input statements for interactive graphics programs 
e Programs that can run on multiple devices 
e Programs that run on any hardware supported by VAX GKS 


Structured Error Handling 


VAX BASIC supports structured error handling with WHEN ERROR 
constructs. When an error occurs during execution of statements in a 
protected block of code, the error is handled by the associated attached or 
detached handler. The following new statements and functions enhance 
error handling capabilities: 


e WHEN ERROR 

e RETRY 

e¢ CONTINUE 

e HANDLER, EXIT HANDLER, and END HANDLER 
e OPTION HANDLE 

e CAUSE ERROR 

¢ RMSSTATUS and VMSSTATUS 


Although the new WHEN ERROR constructs are the preferred method 
for error handling, ON ERROR statements are supported for compatibility 
with previous versions of BASIC. 


Optional Line Numbers 


Line numbers are no longer required in VAX BASIC programs. A 

VAX BASIC program can have no line numbers at all, or it can use the 
traditional line numbered statements; both are valid. A program with 
a line number on the first nonblank line is treated as a line-numbered 
program by the compiler. In the BASIC environment, programs with 
no line numbers must be created with a text editor or copied into the 
environment with the OLD command. 


Array Bounds 


You can now specify the lower bound for any or all dimensions of non- 
virtual arrays. Previously, VAX BASIC arrays could only be zero-based. 
In addition, two new functions, LLOUND and UBOUND, allow you to 

retrieve the lower and upper bounds of array dimensions. 
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Improvements for Procedure Invocations 


This version of VAX BASIC includes additional flexibility for procedure 
invocations: 


e If an external function is called as a procedure, VAX BASIC performs 
parameter validation exactly as if the declared function had been 
invoked as a function. 


e The new keywords ANY and OPTIONAL ease parameter passing to 
non-BASIC routines. 


e Additional functionality has been added to the LOC function so that 
the address of an external function can be accessed. 


PRINT USING Format Strings 


Constant PRINT USING format strings are precompiled at compile time. 
Significant run-time performance gains can be achieved by recompiling 
programs that use constant format strings. 


Single Keystroke Input 


The new function INKEY$ allows you to detect a single keystroke typed at 
a terminal. Function and keypad keys return a descriptive text string, for 
example, "F17", and control characters return a single ASCII code. 


1/O Enhancements 
The following features have been added to enhance I/O capabilities: 


e STREAM files are accessible with the OPEN statement. 


e A WAIT clause can be added to the GET and FIND statements. This 
clause instructs VAX BASIC to wait on locked records rather than 
immediately returning the error RECBUCLOC (ERR = 154). 


¢ The new keywords NX (next) and NXEQ (next or equal to) are syn- 
onyms for GT and GE, respectively. These keywords make the GET 
and FIND statements more meaningful if an indexed file is accessed 
with descending keys. 


Miscellaneous Features 


The new PROGRAM statement allows you to optionally name a main 
program unit. This name becomes the module name of the compiled 
source. 


You can return a procedure value or the status of an image upon 
exiting with the following statements: 


— END/EXIT PROGRAM 
— END/EXIT FUNCTION 
— END/EXIT DEF 


By default, VAX BASIC calls VAX EDT from the environment. The 
user or the system manager can select callable VAX EDT, the VAX 
Text Processing Utility (VAXTPU), or the VAX Language-Sensitive 
Editor as the default editor. Start-up time for editing files within 
the environment is shorter as it is no longer necessary to spawn a 
subprocess to access editors that are callable. 


System managers can prevent users escaping to DCL level from the 
environment by setting the user’s subprocess limit (PRCLM) to zero. 
A subprocess limit of 1 was previously required so that a user could 
use an editor within the environment. 


New extensions to the OPTION statement include the following: 
— OPTION ANGLE = degrees-or-radians 

— OPTION HANDLE = severity-level 

— OPTION CONSTANT TYPE = data-type 

— OPTION OLD VERSION = CDD 


The MID$ function can now be on the left side of an assignment 
statement. This feature allows partial string replacement. 


VAX BASIC statements, compiler directives, labels, and comment lines 
can now begin in column 1. 


You can include files from a text library with the %INCLUDE 
directive. 


The suffixes $ (for strings) and % (for integers) are allowed on explic- 
itly declared variables and constants. 


Extensions to the REMAP and MAP DYNAMIC statements allow you 
to redefine the storage allocated to a previously declared static string 
variable. 


New functions MAX and MIN are provided for the comparison of a 
series of arguments. 


XXxxlli 


XXXIV 


The new MOD function divides one numeric argument by another 
and returns the remainder. 


A new compiler directive, %PRINT, allows you to print a message 
during the compilation of a source program without aborting the 
compilation. 


The new lexical directive % DECLARED allows you to determine 
whether or not a lexical variable has been declared. 





DEVELOPING VAX BASIC PROGRAMS ON VAX/VMS 


Chapter 1 


Overview of the VAX BASIC Language 


This brief overview highlights the features of the VAX implementation of 
BASIC. The features listed here are described fully in subsequent chapters 
of this manual, as well as in the other two manuals in the documentation 
set. 


BASIC was originally developed for students with little or no program- 
ming experience. Since then, BASIC has become one of the most widely 
used programming languages and is available on almost every computer 
system. The VAX implementation of BASIC has evolved beyond the 
original design; however, VAX BASIC still supports all of the traditional 
features of the original language in addition to more recent programming 
techniques. It has become much more than a teaching tool, and is used in 
a wide variety of sophisticated applications. 


VAX BASIC is a powerful structured programming language designed for 

novice and application programmers alike. The language provides you 

with both a highly interactive programming environment and a high- 

performance development language. VAX BASIC supports such language 

constructs as 

¢ Code without line numbers (traditional line numbers are optional) 

¢ Control structures, such as SELECT CASE 

e Explicit variable declarations 

e Capabilities for handling dynamic strings 

e Adaptable file-handling capabilities for terminal-format files, and the 
full range of RMS facilities 

e Global and local run-time error handling with WHEN ERROR blocks 


e Compile-time directives 
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e A variety of data types, including packed-decimal and user-defined 
records 


e Extensive error checking with meaningful error messages 


e Thirty-one-character names for variables, labels, functions and subpro- 
grams 


VAX BASIC uses the VAX/VMS operating system to its full advantage 
and is integrated with many other DIGITAL products. In particular, VAX 
BASIC supports: 


e Interactive graphics! 
e The VAX standard calling procedures 
e Record definitions included from the VAX Common Data Dictionary 


e¢ Code analysis with the VAX Performance and Coverage Analyzer 
(PCA) 


e Creation of code with the VAX Language-Sensitive Editor 
e Extensive online language help 
e Exchange of data with other systems using DECnet 


VAX BASIC supports the features of other BASICs, including PDP-11 
BASIC-PLUS-2. VAX BASIC is a functional superset of BASIC-PLUS-2. 
Compatibility flags for BASIC-PLUS-2 and ANSI Minimal BASIC allow 
you to check whether your VAX BASIC programs will run on other 
systems. 


When you write programs in VAX BASIC, you can choose between two 
program development methods: developing programs at DCL command 
level, or developing programs from within the BASIC environment. When 
you develop programs at DCL level, you write your source program with a 
text editor, then compile, link, and run the program with commands to the 
VAX/VMS operating system. Alternatively, when you develop programs 
within the BASIC environment, you simply type the DCL command 
BASIC to enter the environment, enter your program, then execute it with 
the VAX BASIC command RUN. 


The chapters in Part I of this manual show you how to get started on the 
VAX/VMS system and how to develop programs both at DCL command 
level and within the BASIC environment. 


1 The optional graphics capabilities are discussed in Programming with VAX BASIC Graphics. 
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Chapter 2 


Introduction to the VAX/VMS Operating 
System 


When you develop VAX BASIC programs on the VAX/VMS operating 
system, you use commands that are part of the DIGITAL Command 
Language (DCL). This chapter explains how to use a VAX/VMS system. 
More specifically, this chapter discusses how to 

e Log in to and out of the VAX/VMS system 

e Access the HELP facility 

e Use DCL commands 

e Create directories and subdirectories 

e Use DCL file-handling commands 

e¢ Develop command procedures 

e Develop VAX BASIC programs 


For a complete list of DCL commands, see the VAX/VMS DCL Dictionary. 
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2.1 Logging In and Out 
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Before you can log in to the VAX/VMS operating system, you must have 
an account set up in your name. Your system manager is generally the 
person responsible for establishing this account and will provide you with 
both your user name and password. Both of these are unique to your 
session and distinguish you from other users on the system. Once you are 
an authorized user, you can regularly access the system. 


When you log in, the system prompts you for your user name and pass- 
word. When you enter your user name, each character is displayed, or 
echoed, at the terminal. However, when you enter your password, no 
characters are echoed. This enables you to protect your account from 
others who may try to access it. For example: 


RET 
Username: SMITH 
Password: 
$ 


The system uses the dollar sign ($) as a prompt. When this prompt 
is displayed, it indicates that the login procedure was successful and 
that you can begin entering commands. If you enter your user name 
or password incorrectly, the system displays an error message. To gain 
access to the system, you must repeat the login procedure. 


To change your password, type the SET PASSWORD command and press 
the RETURN key as shown in the following example. The system prompts 
you for your current password. The system then prompts you for your 
new password, which can have up to 31 characters with any combination 
of the letters A through Z, the numbers 0 through 9, a dollar sign ($), and 
an underscore (_—). 


$ SET PASSWORD 


Old password: 
New password: RET 
Verification: 


To verify that you have entered your password correctly, the system 
prompts you to enter your new password again. If the two new passwords 
do not match, your original password remains in effect. 


To end the current session, enter the LOGOUT command: 


$ LOGOUT 
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The system responds with the following message: 


SMITH logged out at DD-MMM-YYY HH:MM 


2.2 Accessing the HELP Facility 


The VAX/VMS system has an online HELP facility that is useful if docu- 
mentation on a particular command is not readily available. To gain access 
to the HELP facility, you use the DCL command HELP. For example: 


$ HELP (RET] 


The system displays a list of topics for which help is available and prompts 
you for a topic. If you want information on a specific command, such as 
the DCL command BASIC, type that command after the topic prompt. For 
example: 


Topic? BASIC 


The system displays a description of the command, and lists all of the 
available VAX BASIC qualifiers, parameters and other topics for which 
help is available. It then prompts you for a subtopic. 


BASIC Subtopic? /SHOW 


If you already know which subtopic you want information on, you can 
type the HELP command followed by the BASIC topic and the subtopic 
you want help on. For example: 


$ HELP BASIC/SHOW 


Note that all language HELP is available only from within the BASIC 
environment or from within the VAX Language-Sensitive Editor. 


To exit from the HELP facility, press CTRL/Z. Once the dollar sign 
prompt is displayed, the system is ready to accept a new command. 
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2.3 Entering and Editing DCL Commands 
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Once you have gained access to the system, you can use DCL commands 
to perform specific tasks. DCL commands are words, generally verbs, 
that describe the action they perform. Following are some of the most 
important rules for using DCL commands. Other rules are described in 
the VAX/VMS DCL Dictionary. 


e You can typically truncate any command name or qualifier name 
to four characters. Fewer than four characters is acceptable if the 
truncated name is unique to the command that you want. 


¢ You must precede each qualifier name with a single slash character 
(/). 


e¢ You can type commands in either upper- or lowercase letters. 


e If you omit a required parameter (for example, a file specification), the 
DCL command interpreter will prompt you for it. 


e You can type a command on as many lines as you wish, as long as 
you end each line (except the last) with a hyphen (-—). 


e After you have typed a complete command line, you must press 
RETURN to execute the command. 


If you enter a command incorrectly (for example, if you misspell a com- 
mand or qualifier name), the command interpreter issues an error message 
and you must either retype the entire command or edit the command and 
then reenter it. Command line editing enables you to correct errors in 
lengthy command lines and saves you the trouble of retyping the entire 
line. 


To edit DCL command lines, you can use various control characters as 
well as keypad keys. The following list describes some of these editing 
functions: 


DELETE Moves the cursor back one character and erases that 
character. 
Up arrow/(CTRL/B) Displays the most recent command line entered. 


You can display up to twenty previously entered 
command lines by continuing to press CTRL/B or 
the up arrow key. To display command lines in the 
opposite direction, press the down arrow key. 


Left arrow/(CTRL/D) Moves the cursor one position to the left. 
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Right arrow/(CTRL/F) Moves the cursor one position to the right. 


CTRL/U Deletes the current command line and issues a car- 
riage return so you can reenter the entire command 
line. 

CTRL/C and CTRL/Y Cancels or interrupts an entire command line. 


2.4 Understanding the Directory Structure 


A directory is a catalog of files. Each file is distinguished by its name, 
file type, and version number. It is not necessary to specify the complete 
file specification every time you compile, link, or run a source program. 
Under most conditions, it is necessary to specify only the file name. 


Figure 2-1 illustrates a complete file specification. 


Figure 2-1: Complete File Specification 


MYVAX: - USERSSDISK : [SMITH] FIRST—PROG . BAS; 3 


L/L LL 


@node @device @directory @Ofile name @file type @version 


ZK-5407-86 


Specifies a computer system that is part of a DECnet network. 


Identifies the hardware device on which the file is either stored or 
written. 


Specifies the directory in which a file is cataloged. 


Distinguishes a file from others contained in the same directory. A file 
name can have up to 39 characters. 


Identifies the type of data that a file contains. 


eo 80 80890 


Specifies the version number of a file. Each time a file is modified, its 
version number is incremented by 1 
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When you log in to the VAX/VMS operating system, you enter your de- 
fault directory which generally has the same name as the account you log 
in to. This default directory is also called your main or top-level directory. 
The system allows you to create subdirectories from your main directory. 
Subdirectories are helpful in organizing files. For instance, if you are a 
multilanguage user, it may be helpful for you to keep all of your VAX 
BASIC programs separate from your VAX COBOL programs. To create a 
subdirectory, you issue the DCL command CREATE/DIRECTORY. In the 
following example, the directory BASIC_PROG.DIR is created. You can 
then specify the subdirectory name [SMITH.BASIC_PROG] in commands 
or programs. 


$ CREATE/DIRECTORY [SMITH.BASIC_PROG] 


To move from one directory to another, you use the SET DEFAULT 
command as shown in the following example: 


$ SET DEFAULT [SMITH.COBOL_PROG] 


The number of subdirectories you can create is limited only by the amount 
of disk space you have available. Figure 2-2 illustrates the concept of 
directory hierarchies. 
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Figure 2—2: A Directory Hierarchy 





A volume’s Master File Directory (MFD) 


$DIRECTORY [000000] contains entries for the user file 
directories (UFDs) on the volume. 


















MALCOLM.DIR 
301300.DIR 
HIGGINS.DIR 
301301.DIR 



























































LEVEL 
$DIRECTORY [HIGGINS] __E@ch UFO lists the files belonging 1) 
to that directory, and can contain 
PAYROLL.DIR entries for additional directories, 
USER.DOC called subdirectories. 
EMO.LIS 
patho $DIRECTORY [HIGGINS.PAYROLL] @ 
INFO.COM A subdirectory can catalog files 
SOURCE.DIR and/or additional subdirectories. 
LISTINGS.DIR The subdirectory file named 
DATA.DIR [HIGGINS]PAYROLL.DIR 
DIRECT.DOC lists additional subdirectory files. 
The subdirectory file named [HIGGINS.PAYROLL]DATA.DIR 
lists additional subdirectory files. 
$DIRECTORY [HIGGINS.PAYROLL.DATA] 
JANUARY.DIR $DIRECTORY [HIGGINS.PAYROLL.LISTINGS] © 
FEBRUARY.DIR § 
.D DIRECTORY [HIGGINS.PAYROLL.SOURCE 
mene e FICA.LIS } 
TAXES.LIS 
FICA.BAS 
TAXES.MAR 
PAYROLL.BAS 
$DIRECTORY [HIGGINS.PAYROLL.DATA.MARCH] 4 ] 
FICA.DAT 
STATETAX.DAT 
FICA.DAT FEDTAX.DAT 
FICA.DAT STATETAX.DAT EMPTTL.DAT 
STATETAX.DAT FEDTAX.DAT : 
FEDTAX.DAT Erna 
EMPTTL.DAT nextlevel.DIR 


ZK 5536 86 





Introduction to the VAX/VMS Operating System 2-7 


Often, you may refer to files that are contained in your directory hierarchy 
but that are not contained in your current default directory. Two special 
symbols exist to make references easier: the ellipsis (...) and the hyphen 
(-). The ellipsis is used to search down a directory hierarchy and the 
hyphen is used to search up a directory hierarchy. 


For instance, [SMITH...] refers to the directory [SMITH] and all of the 
subdirectories below [SMITH] in the hierarchy. The directory specification, 
[...BASIC_PROG] refers to all subdirectories named BASIC_PROG below 
the current default directory. You can specify the current default directory 
with empty brackets ([]), and you can refer to the entire hierarchy under 
your current default directory with [...]. 


Hyphens allow you to search up the hierarchy one directory at a time; 
each hyphen stands for one level. For example, if your current default di- 
rectory is [SMITH.BASIC_PROG], you can refer to [SMITH] by specifying 


To delete a subdirectory, you must first remove any files that are contained 
in it and change the protection on the directory file. You can then delete 
the .DIR file. 


Note that you can use both square brackets and angle brackets inter- 
changeably to refer to directories. 


For a more detailed discussion of the directory structure, see the 
Introduction to VAX/VMS. 


2.5 Using DCL File-Handling Commands 


DCL file-handling commands allow you to modify and maintain your 
source programs. The following sections describe how to use DCL com- 
mands to perform common file operations such as displaying files, printing 
and typing files, deleting files, purging files, renaming and moving files, 
searching files, and setting file protection. 


For a complete list of qualifiers to each command and for more detailed 
information, see the VAX/VMS DCL Dictionary or type HELP at the DCL 
prompt followed by the name of the command. 
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2.5.1 Displaying Files 


To display a list of all of the files that are contained in a directory, you 
use the DCL command DIRECTORY. When you enter the DIRECTORY 
command with no parameters or qualifiers, the system displays an entire 
list of all of the files that are contained in your current directory. For 
example: 


$ DIRECTORY 

Directory USER$$DISK: [SMITH] 

PROG1. DIA; 22 PROG1 . EXE; 2 PROG1 . OBJ; 50 PROG1 . BAS ; 63 

If you want to know how many versions of a specific file exist in your 


current directory, you enter the DIRECTORY command along with a 
specific file name and file type as shown in the following example: 


$ DIRECTORY PROG1.BAS 
Directory USER$$DISK: [SMITH] 
PROG1 . BAS; 53 

Total of 1 file. 


The system displays a list of all the versions of the file that currently exist. 


However, if you wish to view only a selected group of files that contain 
a specific file type, you can use an asterisk (*) or a percent sign (%) as 
a wildcard character. The asterisk signifies any number of characters, 
including zero, whereas the percent sign signifies exactly one character. 
Therefore, *.BAS represents all files that end with the file type, BAS 
whereas 3%.BAS represents only those files that contain two characters 
for a file name, where 3 is the first character. For example: 


$ DIRECTORY +*.OBJ 

Directory USER$$DISK: [SMITH] 

PROG1 .OBJ;53 PROG2 .0BJ;54 PROG4 . OBJ; 55 
Total of 3 files. 


The system displays only those files that end with the file type OBJ. 
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2.5.2 Printing and Typing Files 


To examine the contents of a file, you can use either the DCL command 
PRINT or the DCL command TYPE. The PRINT command allows you to 
output the contents of a file to a line printer whereas the TYPE command 
allows you to output the contents of a file to your terminal screen. 


In the following example, the PRINT command outputs the file FIRST_ 
PROG.BAS to a printer: 


$ PRINT FIRST_PROG.BAS 


By default, the system prints the most current version of FIRST 
PROG.BAS. To print a specific version of FIRST_PROG.BAS, you must 
specify a version number. For instance, in the following example, the 
system prints the second version of FIRST_PROG.BAS: 


$ PRINT FIRST_PROG.BAS;2 


With the PRINT command, you can specify command qualifiers. For 
example, the /AFTER qualifier specifies that the job not be printed until a 
specific time of day. For a complete list of all of the command qualifiers 
available with the PRINT command, see the VAX/VMS DCL Dictionary. 


With the TYPE command, you can display the contents of a file on your 
terminal screen. If you specify the /PAGE qualifier, you can display one 
screen of text at a time. If you do not specify the /PAGE qualifier, you 
can press CTRL/S to interrupt the display for closer examination of a 
particular section and then resume the display by pressing CTRL/Q. If 
your keyboard has a NOSCROLL or a HOLD SCREEN key, you can use it 
to toggle between interrupting and resuming the display. 


2.5.3 Deleting Files 


To delete a file, you use the DCL command DELETE. With the DELETE 
command, you must specify the file name, the file type, and the version 
number of the file you want to delete. For instance, in the following 
example, the system deletes the first version of FIRST_PROG.BAS. 


$ DELETE FIRST_PROG.BAS;1 


If you want to delete all versions of a file, you can use an asterisk (*) as a 
wildcard character. For example: 


$ DELETE FIRST_PROG.BAS; * 
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Similarly, if you want to delete all files with a particular file type, you can 
use the asterisk (*) or the percent sign (%) as a wildcard character. For 
instance, in the following example, the system deletes all files that have 
the file type LIS: 


$ DELETE *.LIS;* 


You can specify command qualifiers with the DELETE command. For 
instance, if you specify /CONFIRM, a request is issued before each 
individual DELETE operation so that you can confirm that the operation 
should be performed on a particular file. 


2.5.4 Purging Files 


The DCL command PURGE deletes all but the most recently modified 
version of files. Unlike the DELETE command, you can specify the 
PURGE command without specifying a file name or file type. The system 
deletes all files except the most recent version in your current directory. 


$ PURGE 


By default, only the most recent version of each file is kept. You can, 
however, specify the number of versions that are kept by specifying the 
/KEEP qualifier. This command qualifier specifies the maximum number 
of versions of a specified file to be kept in your directory. For instance, in 
the following example, the system deletes all but the two highest versions 
of FIRST_PROG.BAS. 


$ PURGE FIRST_PROG.BAS/KEEP=2 


2.5.5 Renaming and Moving Files 


To change the identification of one or more files, use the DCL command 
RENAME. For instance, in the following example, FIRST_PROG.BAS is 
changed to SECOND_PROG.BAS. 


$ RENAME FIRST_PROG.BAS SECOND_PROG.BAS 


Note that because a version number is not specified, the most current 
version is renamed by default. 
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You can also use the RENAME command to move a file from one directory 
to another. For instance, in the following example, the file SECOND— 
PROG. BAS is moved from the directory [SMITH] to the aay 
[SMITH.BASIC_PROG]: 


$ RENAME [SMITH]SECOND_PROG.BAS [SMITH.BASIC_PROG] 


To move an entire set of files that have common file name or file type, 
you can use the asterisk (*) as a wildcard character. For instance, the 
following command line changes the directory name of all files that 
contain the file name SECOND_PROG. 


$ RENAME [SMITH]SECOND_PROG.*;* [SMITH.BASIC_PROG] *. *;* 


2.5.6 Searching Files 


To search a file or a group of files for a specified string, use the DCL 
command SEARCH. This command allows you to search the contents of 
a specified file or group of files for a particular string or strings and lists 
all of the lines in which the string or strings appear. In the following 
example, the directory [SMITH.BASIC_PROG] is searched for any files 
that contain the string “Course_Data”: 


$ SEARCH [SMITH.BASIC_PROG] *.*;* "Course_Data" 


2.5.7 Setting File Protection 


To prevent others from gaining access to a file, you use the SET 
FILE/PROTECTION command. With this command, you specify user 
categories with access types. Table 2-1 lists the four user categories and 
Table 2-2 lists the four access types. 
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Table 2-1: 
User Category 
OWNER 
GROUP 


WORLD 
SYSTEM 


File Protection User Categories 


Description 
The user who created the file 


All users, including the owner, who have the same 
group number in their user identification codes 
(UICS) as the owner of the file 


All users 


All users who have the same system privilege 
(SYSPRV), or low group numbers (usually from 1 
through 10) 


Table 2—2: File Access Variations 


Access 
READ 
WRITE 
EXECUTE 


DELETE 


Description 
The ability to examine, print, or copy a file 
The ability to modify or write a file 


The ability to execute a file that contains executable 
program images 
The ability to delete a file 


When you specify the SET FILE/PROTECTION command, the class 
names and access types can be spelled out or abbreviated to the first 
letter. For example, you may want to give system users and your project 
members complete access to the file TEST.BAS, and give others read 
access only. To do this, you would enter the following command: 


$ SET FILE TEST.BAS/PROTECTION = (S:RWED,O:RWED,G:RWED,W:R) 
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2.6 Using Command Procedures 


A command procedure is a group of DCL commands in a file that can be 
executed by the DCL command interpreter. You can use command proce- 
dures to generate sequences of command lines that you type frequently. 
For example, you could create a command procedure that compiles, links, 
and runs your source programs while checking for error status. Moreover, 
you could create a command procedure that deletes all files that end with 
a particular file type. Instead of typing each command separately, you 
would execute the command procedure. 


The following sections briefly discuss the rules for defining DCL symbols 
and logical names as well as how to create and execute a command 
procedure. In addition, this section contains a sample command procedure 
and a sample LOGIN.COM file. For more information, see the Guide to 
Using DCL and Command Procedures on VAX/VMS. 


2.6.1 Defining DCL Symbols and Logical Names 
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You define a symbol by placing the equal sign (=) or the double equal 
sign (==) between the symbol and the string it represents. If you use the 
double equal sign operator, the system inserts the symbol in the global 
symbol table; if you use the equal sign operator, the system inserts the 
symbol in a local symbol table. When a symbol is local, it is recognized 
only within the procedure in which it is contained. However, when a 
symbol is global, it is recognized by many other procedures. 


For example, the following command defines the global symbol BASIC as 
a command to invoke the VAX BASIC compiler, with two added qualifiers: 


$ BASIC == "BASIC/DEBUG/LIST" 


Briefly, the VAX/VMS system creates a global symbol table for you 
when you log in. Then, each time you execute a command procedure, 
the system creates a new command level and a local symbol table for 
that level. If one command procedure executes another procedure, the 
system creates another new—lower—command level and another local 
symbol table, and so forth. Every command level can access the symbols 
in the global symbol table, as well as symbols in local symbol tables at 
higher command levels. In other words, you can define local symbols in 
a command procedure that are available to lower-level procedures. The 
VAX/VMS DCL Dictionary describes symbol tables in detail. 


Introduction to the VAX/VMS Operating System 


Note that the system discards local symbols and their values when a 
procedure exits. A command procedure can create local symbols, but the 
symbols are deleted when the procedure ends. However, when you define 
local symbols at DCL command level, these symbols remain until you 
explicitly remove them or until you log out. 


You can pass information to a higher-level command procedure by 
defining a global symbol to contain the information. Because there is 
only one global symbol table, and it is accessible at all command levels, 
the higher-level command procedure can test the value of the symbol. 


To allow abbreviations of a symbol, insert an asterisk (*) in the symbol 
where you want to end the acceptable abbreviation. For example, if you 
wanted to abbreviate the command BASIC to BAS, you could define a 
symbol as follows: 


$ BAS*IC == "BASIC/DEBUG/LIST" 


Once you have defined this symbol, you can type BAS (plus any remain- 
ing letters in the command) to invoke the VAX BASIC compiler with the 
/DEBUG and /LIST qualifiers. Note that the double equal sign in this 
symbol definition causes the creation of a global symbol. 


You can determine the definition of a symbol by typing SHOW SYMBOL, 
followed by the symbol name. For example: 


$ SHOW SYMBOL BAS 
BAS*IC == "BASIC/DEBUG/LIST" 


To delete a symbol, type DELETE/SYMBOL, followed by the symbol 
name. If you do not specify a symbol table qualifier, /LOCAL is the de- 
fault. If the symbol is in the global table, type DELETE/SYMBOL/GLOBAL 
followed by the symbol name. For example, you could delete the symbol 
BASIC that you had previously defined, by typing the following: 


$ DELETE/SYMBOL/GLOBAL BASIC 


To create a logical name, you use either the DCL command DEFINE or 
the DCL command ASSIGN. A logical name is a name that is equated to 
an equivalence string, or a list of equivalence strings. For example, the 
following command assigns the logical name INFO to the file specification 
USER$$DISK:[SMITH]INFO.DAT;12: 


$ DEFINE INFO USER$$DISK: [SMITH] INFO.DAT;12 
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You can determine the definition of a logical name by typing SHOW 
LOGICAL, followed by the logical name. For example: 


$ SHOW LOGICAL INFO 
"INFO" = "USER$$DISK: [SMITH] INFO.DAT;12" (LNM$PROCESS_TABLE) 


When you create a logical name, it is maintained in a logical name table. 
For more information on logical name tables, see the VAX/VMS DCL 
Dictionary. 


You can keep a file of symbols and logical names for the system to define 
every time you log in, thus creating a set of personal commands for 
special purposes. For information on login command procedures, see 
Section 2.6.4. 


2.6.2 Creating and Executing Command Procedures 
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To create a command procedure, you can invoke a text editor or you can 
use the DCL command CREATE. If you use the default file type COM, 
you need not include the file type when you execute the procedure. 


Once you have created your command procedure, you can execute it either 
interactively or in batch. To execute a command procedure interactively, 
type the at sign (@) execute procedure command followed by the name 
of the file. In the following example, the procedure SAMPLE.COM is 
executed. 


$ OSAMPLE 


To execute a command procedure in batch, you use the DCL command 
SUBMIT. This command allows you to submit your procedure to a system 
batch job queue for execution. Once the job completes, the system prints 
a log file indicating the status of the job and then deletes the log file from 
your directory. In the following example, SAMPLE.COM is placed in the 
system batch job queue. A log file entitled SAMPLE.LOG will be created. 


$ SUBMIT SAMPLE 
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2.6.3 Sample Command Procedure 


The following command procedure is included to help you understand 
how command procedures can aid in the programming process. This 
command procedure incorporates many of the DCL commands discussed 
throughout this chapter. Any text that follows an exclamation point (!) is 
interpreted by the DCL command interpreter as a comment and is ignored. 


!The following command procedure tests to see if the file name you 
input exists. If it does exist, the procedure will automatically 
!compile, link, and run your source program. If the file does not 
‘exist, the procedure will ask you if you want to create the file. 
!If you respond YES, the default text editor is invoked so that you 
‘can create the source file. 

i 

! 

IF P1 .EQS. "" THEN INQUIRE Pi "FILE NAME" 

FILETYPE = ".BAS" 

FILESPEC = P1 + FILETYPE oO 
IF F$SEARCH(FILESPEC) .EQS. "" THEN GOTO MESSAGE 

SHOW SYMBOL FILESPEC 

' 

t 

! 

ON ERROR THEN GOTO PRINT_ROUTINE 

WRITE SYS$OUTPUT "Compiling..." 2] 


BASIC/LIST 'P1' 
! 


° 


WRITE SYS$OUTPUT "Linking..." 13) 
LINK 'P1! 

WRITE SYS$OUTPUT "Running..." 4 ) 
SET NOON 

DEFINE/USER_MODE SYS$INPUT SYS$COMMAND 

RUN 'P1' 

GOTO END 

' 


PDH HDA HD HM DH HM DH HD DH @ DW DH WH D © DH © BH DH © © © © WH © HH OH WH &H 
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$ PRINT_ROUTINE: 5) 


$ WRITE SYS$OUTPUT "Error in program - processing stops" 

$ PRINT 'P1' 

$ END: 

$! 

$ PURGE 

$! 

$ EXIT 

$! 

$ MESSAGE: © 
$ WRITE SYS$OUTPUT "Can't find requested file" 

$ INQUIRE ANS "Do you want the file created?" 

$ IF ANS .EQS. "YES" THEN GOTO EDIT_ROUTINE 

$ EXIT 

$! 

$ EDIT_ROUTINE: 7) 
$  DEFINE/USER_MODE SYS$INPUT SYS$COMMAND 

$ WRITE SYS$OUTPUT "Invoking editor..." 

$ EDIT FILESPEC 

$ EXIT 

@ Marks the beginning of the command procedure and prompts the user 


for a source file name if the user has not supplied one. If the file is 
not found, control is transferred to a routine called MESSAGE. 


Marks the start of the compilation process. The procedure outputs an 
informational message and invokes the VAX BASIC compiler. 


Marks the start of the linking process. Again, the procedure outputs 
an information message and invokes the VAX/VMS Linker. 


Marks the start of the running process. Once again, the procedure 
outputs an informational message and runs the program. The input 
device is equated to the user’s terminal to allow data to be entered. 


Identifies the actions of the command procedure in the event an 
error occurs during execution. When an error does occur, control is 
transferred to this routine. The procedure outputs an informational 
message and prints the LIS file. 


Marks the routine that alerts the user that the source file has not been 
found. If the user chooses to create the file, control is transferred to 
the routine called EDIT_ROUTINE. 


Marks the start of the edit routine. Again, the input device is equated 
to the user’s terminal to allow data to be entered. The procedure then 
outputs an informational message and creates the supplied source file 
by invoking the user’s default text editor. 
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2.6.4 Login Command Procedures 


If you are a frequent user of the VAX/VMS system, you may find that you 
are typing the same long command lines on a regular basis. To avoid such 
repetition, you can create a special command procedure that contains these 
commands and statements. This special command procedure is called a 
LOGIN.COM file. 


When you log in, the system automatically searches your default device 
and directory for a file named LOGIN.COM. If the file exists, the system 
automatically executes the commands within that file. 


A LOGIN.COM file might appear as follows: 


‘If the current process is noninteractive then exit 
IF F$MODE() .NES. "INTERACTIVE" THEN EXIT 
! 


ETI TTE CITE TTL rrr r rr TT er err rt ererr rere ere rey: 
ix Convenient Commands * 
PTT TTS L ICTS TLeTITTir tri rerrrererr rere rere sf 
t 

PURGE == "PURGE/KEEP=2/CONFIRM" 

ST == "SHOW TIME" 

QUE == "SHOW QUEUE" 

M*AIL == "MAIL" 

i 


PTTL TErrerrrr er rerrrr errr eerie coer rrr eee re | 

1% Symbols for my directories * 

Er rrIrirorrerrierrerr eres ererr rere re rer ery 2 

! 

ROME "SET DEFAULT [SMITH] " 

WORK "SET DEFAULT [SMITH.WORKSP]" 

EXAMPLES == "SET DEFAULT [SMITH.PROG_EXAMPLES] " 

! 

PT TEILOLOLCCOLT ITT rrrrerrercrerere rrr EL Te rrer tro rer Sf rr ety | 
'* Logical names for the people I frequently send mail to * 
1 he fe oe oe a oe oe oo oR RR I kk ICE i oi aC Cf i ke ake i i 2 a fe a ak a ask ate os 
! 

DEFINE JEN MYVAX: : BROWN 

$ DEFINE SUE MYVAX: : KELLY 

$ DEFINE BOB MYVAX: : CONNELL 

$ EXIT 


BAHAPAKREHODRKDPPAHYHBH DHHS HH WH HW & WM © HH & 


For more information on creating a login command file, see the Guide to 
Using DCL and Command Procedures on VAX/VMS. 
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2.7 DCL Commands for Program Development 


VAX BASIC can function as both a standard compiler or as a program- 
ming evironment. When using VAX BASIC as a standard compiler, 

you create programs at DCL command level. This section describes the 
DCL commands that are used to create, compile, link and run a VAX 
BASIC program on a VAX/VMS system. These commands are illustrated 
in Figure 2-3. For a more detailed description of each command, see 
Chapter 4. For more information on using VAX BASIC as a programming 
environment, see Chapter 3. 


Figure 2-3: DCL Commands for Developing Programs 


COMMANDS ACTION INPUT/OUTPUT FILES 


$ EDIT AVERAGE.BAS 
Use the file type of BAS to Create a AVERAGE BAS 
indicate the file contains a source program 
VAX BASIC program 


wn 


BASIC AVERAGE 

The BASIC command 
assumes the file type of an 
input file is BAS 


AVERAGE OBJ 
Compile the (AVERAGE.LIS) 

source program 

(If you use the/L/ST Iibraries 

qualifier. the compiler 

creates a listing file.) 


$ LINK AVERAGE 
The LINK command assumes Link the AVERAGE. EXE 
the file type of an input file object module (AVERAGE.MAP } 


is OBJ. 


vA WAL 





(If you use the /MAP qualifier. 
the linker creates a map file.) 


wn 


RUN AVERAGE 

The RUN command assumes 
the file type of an image is 
EXE. 


Run the 


executable 
image 
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The following example shows each of the commands shown in Figure 2-3 
executed in sequence. 


$ EDIT/EDT FIRST_PROG. BAS 
$ BASIC FIRST_PROG 

$ LINK FIRST_PROG 

$ RUN FIRST_PROG 


To create a VAX BASIC source program at DCL level, you must invoke a 
text editor. In the example shown above, the VAX EDT editor is invoked 
to create the source program FIRST_PROG.BAS. You can, however, 

use another editor, such as the VAX Text Processing Utility (VAXTPU) 
or the VAX Language-Sensitive Editor. BAS is used as the file type to 
indicate that you are creating a VAX BASIC source program. BAS is the 
conventional file type for all VAX BASIC source programs. 


When you compile your program with the BASIC command, you do not 
have to specify the file type; VAX BASIC searches for BAS by default. 


If your source program compiles successfully, the VAX BASIC compiler 
creates an object file with the file type OBJ. However, if the VAX BASIC 
compiler detects errors in your source program, the system displays each 
error on your screen and then displays the DCL prompt. You can then 
reinvoke your text editor to correct each error. 


You can include command qualifiers with the BASIC command. 
Command qualifiers cause the VAX BASIC compiler to perform addi- 
tional actions. For instance, in the following example, the /LIST qualifier 
causes the VAX BASIC compiler to produce a listing file. 


$ BASIC/LIST FIRST_PROG 


For a complete list and explanation of all of the command qualifiers 
available with the BASIC command, see Chapter 4. 


Once your program has compiled successfully, you invoke the VAX/VMS 
Linker to create an executable image file. The VAX/VMS Linker uses the 
object file produced by VAX BASIC as input to produce an executable 
image file as output. 


You can specify command qualifiers with the DCL command LINK. For a 
complete list and explanation of all the command qualifiers available with 
the LINK command, see Chapter 4. 


Once the executable image file has been created, you run your program 
with the DCL command RUN. 
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Chapter 3 


Developing Programs in the BASIC 
Environment 


The BASIC environment has capabilities and features that make the 
process of program development easier for both novice and expert users. 
This chapter describes how to work within the BASIC environment. 


3.1 Entering the Environment 


To enter the BASIC environment, type the DCL command BASIC and 
press RETURN. VAX BASIC responds with an identification line and the 
Ready prompt. 


$ BASIC [RET] 
VAX BASIC V3.0 


Ready 


Once you are in the BASIC environment, you interact directly with the 
compiler. In this mode of operation, you can enter any of the following: 


e VAX BASIC program lines 
¢ Immediate mode statements 
@ Compiler commands and qualifiers 


When you enter program statements, VAX BASIC stores them in ascending 
line number sequence as part of the current program in memory. If you 
enter a program line with the same line number as an existing program 
line, the new line replaces the oid one. 
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When you create a program in the environment, the first line of the 
program must have a line number. If you enter a subsequent program line 
without a line number, you must precede it with a space or a tab. Inside 
the environment, only those program lines that begin with line numbers 
can start in the first character position on a line. 


NOTE 


To develop programs in the environment that have no line 
numbers at all, you must use an editor or copy your program 
into the environment with the OLD command. 


If a program line is too long for one text line, you can continue it by 
typing an ampersand ( &) and pressing RETURN. (Note that only spaces 
and tabs are valid between the ampersand and the carriage return.) 


See Section 3.3 for more information about immediate mode statements 
and Section 3.5 for more information about VAX BASIC compiler 
commands. 


3.2 Creating and Running Programs 


Inside the BASIC environment, there are two ways to type in and edit a 
program. You can type in and edit the program directly using line mode, 
or you can use the compiler command EDIT to invoke a text editor when 
you are in the environment. 


The EDIT command invokes the default text editor for your system. After 
entering the BASIC environment, you can type the EDIT command, create 
your program with a text editor, and then exit from this editor back to 
the environment. At this point, the program you created is the current 
program in memory, and you can now type RUN or RUNNH to compile, 
link, and execute your program. (RUNNH suppresses header information 
such as the name of the program and the time of day.) 


You also have the option of creating your program with a text editor 
accessed from DCL. In this case, once you have created the program, you 
can either enter the BASIC environment and use the OLD command to 
read your program into memory, or compile your program at DCL level. 
Chapter 4 discusses how to compile your programs at DCL level. 


The following example shows a simple program being entered and run 
in the environment. The program accepts three numbers entered at the 
terminal, averages them, and displays the result. 
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Example 
$ BASIC 
VAX BASIC V3.0 


Ready 

NEW FIRSTTRY 

Ready 

10 PRINT "Please enter three numbers" 
INPUT A, B, C 
PRINT "Their average is"; (A+B+C) /3 
END 

RUNNH 

Output 

Please enter three numbers 

75 

?:10.3 

?:4.7 

Their average is 6.66667 

Ready 


In the preceding example, the DCL command BASIC invokes VAX BASIC 
and places you in the BASIC environment. The compiler command NEW 
informs VAX BASIC that you want to create a new program and assigns 
the program a name. Here the program is named FIRSTTRY.BAS. If 
you do not enter a program name with the NEW command, VAX BASIC 
assigns the name NONAME by default. BAS is the default file type. 


The RUNNH command compiles, links, and executes the program you 
create. To save this program, enter the SAVE command at the Ready 
prompt. 


You can execute multiple-unit programs while in the BASIC environment. 
To execute multiple-unit programs, follow these steps: 

1. Compile all subprograms to generate object modules 

2. Use the OLD command to read the main program into memory 


3. Use the LOAD command to read the subprogram object modules into 
memory 


4. Type the RUN command 


Figure 3-1 illustrates how to execute multiple-unit programs. 
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Figure 3-1: Running Multiple-Unit Programs 
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The following is an example of a program that contains multiple units: 


Example 

10 REM This program calls SUBPROGRAM SB1 
20 PRINT "NOW IN MAIN PROGRAM" 

30 CALL SB1 

40 PRINT "BACK IN MAIN PROGRAM" 

50 END 

10 SUB SBi 

20 PRINT "NOW IN SUBPROGRAM" 

30 SUBEND 


To execute this program in the BASIC environment, enter the following 
commands. 
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OLD SB1 
Ready 


COMPILE 
Ready 


OLD MAIN 
Ready 


LOAD SB1i 
Ready 


RUN 


Output 


NOW IN MAIN PROGRAM 
NOW IN SUBPROGRAM 
BACK IN MAIN PROGRAM 
Ready 


If a STOP statement or CTRL/C is encountered in a module other than 
the currently compiled module, VAX BASIC signals “Compiled procedure 
is currently not active”. At this point, you cannot use immediate mode 
statements. 


When you run multiple-unit programs in the BASIC environment, only 
one module is currently compiled. Normally, the currently compiled pro- 
gram is the one you read into memory with the OLD command. However, 
if a source file contains more than one program module, the last one (the 
one closest to the end of the source file) is the currently compiled module. 
In the previous example, MAIN is the currently compiled module. 


For more information on loading multiple object modules, see Section 3.4. 


3.3 immediate Mode 


You do not have to write a complete program in order to use VAX BASIC. 
Many statements are executable in immediate mode. 


Immediate mode statements are BASIC statements that are executed im- 
mediately after you press the RETURN key. Immediate mode statements 
cannot be preceded by a line number, space, or tab and can be used only 
if you are working directly in the environment. 
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In the following example, VAX BASIC interprets the first line as a com- 
ment because it begins with an exclamation point (!). VAX BASIC 
interprets the second line as part of a larger program because it begins 
with a line number. This line will not execute until a RUN command is 
specified. The third line does not begin with a line number, a space, or an 
exclamation point. Therefore, VAX BASIC treats the line as an immediate 
mode statement and immediately displays the specified text. 


Example 


!'In the environment, this is a comment 
10 PRINT 'This is an executable VAX BASIC statement’ 
PRINT ‘THIS IS AN IMMEDIATE MODE STATEMENT’ 


Output 


THIS IS AN IMMEDIATE MODE STATEMENT 
Ready 


The Ready prompt indicates that VAX BASIC is ready to receive compiler 
commands, immediate mode statements, or new program lines. 


You can precede each executable statement with a backslash (\). You can 
also have more than one VAX BASIC statement on a line if you separate 
them with a backslash. However, programs with backslashes are often 
difficult to read. 


Example 


Ready 


A = (54.37 / 1.25 ) \ B = ( 328.15°2) \ PRINT (B/A) 
2475.69 


Unless the compiler has executed a STOP statement, VAX BASIC compiles 
and executes each immediate mode statement as if it were a self-contained 


program. 


Example 


Ready 
PRINT PI * 67.3 
211.421 


Even if the current program has executed a STOP statement, you can still 

perform independent calculations. However, you should understand that 

after a stop, any immediate mode statement referencing program variables 
uses the values assigned in the program. Note that you cannot create new 
program variables after a STOP statement has been executed. 
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If the current program has not executed a STOP statement, each immedi- 
ate mode line exists by itself, and any variables used by the statements on 
that line are temporary. For example: 


Example 


Ready 
A = 2°5 \ PRINT A 
32 


READY 
PRINT A 
0 


The second PRINT statement causes VAX BASIC to display a zero because 
the compiler treats A as a new variable, and initializes it to zero. 


You can use the IF, WHILE, UNTIL, UNLESS, and FOR statement mod- 
ifiers in immediate mode statements. The following example shows how 
you can generate a table of square roots by using the immediate mode 
statement: 


Example 

Ready 

PRINT I, SQR (I) FOR I = 1 TO 10 
1 1 

2 1.41421 
3 1.73205 
4 2 

5 2.23607 
6 2.44949 
7 2.64575 
8 2.82843 
9 3 
10 3.16228 

Ready 


Certain statements are invalid in immediate mode. In general, invalid 
statements are statements that require the allocation of new storage, or 
statements that make no sense in the context of a single line. If you 
try to execute such a statement, VAX BASIC signals the error “Illegal in 
immediate mode”. 
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3.4 Debugging in Immediate Mode 


To debug in immediate mode, you insert STOP statements in your pro- 
gram at the points where you wish to examine the values of variables. 
When VAX BASIC encounters a STOP statement, program execution is 
interrupted. At this point, you can use immediate mode statements to 
display the values of variables or to assign them new values. After chang- 
ing or examining data, you can use the CONTINUE command to resume 
program execution. 


The following restrictions apply when you are debugging in immediate 
mode: 


e You cannot continue execution if you have changed any program code; 
for example, you cannot create new variables after VAX BASIC has 
encountered a STOP statement. Neither can you use the CONTINUE 
command after you have inserted a STOP statement into your pro- 
gram in immediate mode. In both cases, you have changed program 
code and you must reexecute the program with the RUN command. 


e You can debug only one module at a time; VAX BASIC lets you 
examine and change variables only in the current module (the most 
recently compiled module) of a multiple-unit program. 


When you are debugging multiple program units in the environment, you 
should follow these guidelines: 


e Use the OLD command to read in the source file for the module you 
want to debug. This source file becomes the current module, that is, 
the one available for immediate mode debugging. 


e Use the LOAD command to read in the object files for the remaining 
program modules. 


An object module is the file that results from compiling a source file; its 
format is an intermediate step between a source file and an executable 
image. The LOAD command removes any previously loaded object 
modules, whether or not the command specifies any object module files. 
Therefore, you must use a single LOAD command to specify all the object 
files you need. In addition, you must separate multiple object modules 
with plus signs. 


The object files are not linked with the current program or executed until 
you issue the RUN command. Therefore, run-time errors in the loaded 
modules are not detected until you execute the program. 
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When you want to run a program, you can load all the object modules for 
that program and then execute the program with the RUN command. If 
you want to debug a program, you use the OLD command for the module 
you want to debug and then load the remaining program modules. The 
module to be debugged can be either a main program or a subprogram 
because when you enter the RUN command, VAX BASIC transfers control 
to the main program, whether it is in object-module format or source- 
program format. 


For information on using the VAX/VMS Debugger, see Chapter 5. 


3.5 Compiler Commands 


Compiling is the process of translating a source program to an object 
module. An object module is an intermediate step between source code 
and an executable image. It contains information that the linker uses to 
create an image. 


You can compile, link, and execute your programs in the environment 
simply by typing the RUN command. This greatly reduces the number of 
steps you have to go through to develop VAX BASIC programs. When you 
are satisfied with a portion of code, you can simply run that program to 
examine whether or not it functions as expected. If you use the COMPILE 
command instead, you can eliminate all compile-time errors before you 
link and execute the program. 


VAX BASIC has certain defaults that are in effect each time you enter the 
BASIC environment. Unless you explicitly override these defaults, they 
remain in effect until you leave the environment. You can see a listing of 
these defaults by typing the SHOW command when in the environment. 
The following example displays the standard BASIC environment defaults 
that are in effect when you enter the environment: 


SHOW 
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VAX BASIC V3.0 Current Environment Status 22-JUN-1986 10:12:12.05 


DEFAULT DATA TYPE INFORMATION: 
Data type : 
Real size : 
Integer size 
Decimal size : 
Scale factor : 0 
NO Round decimal numbers 


COMPILATION QUALIFIERS IN EFFECT: 


LISTING FILE INFORMATION INCLUDES: 


REAL NO Source 
SINGLE NO Cross reference 
: LONG CDD Definitions 
(15,2) Environment 


NO Override of %NOLIST 
NO Machine code 

Map 

INCLUDE files 


Object file 


Overflow check integers 
Overflow check decimal numbers 
Bounds checking 


FLAGGERS : 
NO Declining features 
NO BASIC PLUS 2 subset 


NO Syntax checking 


Lines 

Variant : 0 DEBUG INFORMATION: 
Warnings Traceback records 
Informationals NO Debug symbol records 
Setup 


Object Libraries 


Ready 


: NONE 


You can override any of these defaults with qualifiers to the COMPILE or 
SET commands, or with the OPTION statement in your program. The fol- 
lowing section lists and describes all the VAX BASIC compiler commands, 
including qualifiers to both the COMPILE and RUN commands. For more 
information on the OPTION statement, see the VAX BASIC Reference 


Manual. 


Table 3-1: 
Command 

! comment 

$ command 
APPEND 


ASSIGN 


COMPILE 


CONTINUE 
DELETE 


VAX BASIC Compiler Commands 

Description 

Identifies a comment. 

Starts a subprocess to execute the specified DCL command. 


Merges the specified program with the program currently in 
memory. 


Assigns a logical name to a complete file specification (the 
equivalence name). 


Generates an object module (file type OBJ) from a VAX BASIC 
source program. 


Resumes execution after a STOP statement or a CTRL/C. 


Erases the specified line or lines from a VAX BASIC source 
program. 
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Table 3-1 (Cont.): VAX BASIC Compiler Commands 


Command 


EDIT 
EXIT 
HELP 
IDENTIFY 


LIST 
LISTNH 
LOAD 
LOCK 


NEW 


OLD 
RENAME 
REPLACE 


RESEQUENCE 


RUN 


RUNNH 
SAVE 


SCALE 


Description 


Changes source text or calls a text editor. 
Returns to DCL command level. 
Displays HELP text. 


Causes VAX BASIC to print an identification header on the 
terminal. 


Displays the current source program on the terminal. 
Displays the current source program without header information. 
Loads an object module into memory. 


Specifies default values for compiler command qualifiers (identi- 
cal to the SET command). 


Clears memory for the creation of a new program and assigns a 
new program name. 


Reads a specified VAX BASIC source program into memory. 
Changes the name of the program currently in memory. 


Replaces a stored program with the program currently in 
memory. 


Supplies new line numbers for the program currently in memory. 

Executes the program currently in memory, or a specified VAX 

BASIC source program. The program in memory can be: 

e A VAX BASIC source program placed in memory with the 
OLD command 


¢ One or more object modules placed in memory with the 
LOAD command 


e A combination of the first two 


Identical to RUN but does not display header information. 


Creates a copy of the current source program on a specified 
device. 


Controls accumulated round-off errors for numeric operations. 
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Table 3-1 (Cont.): VAX BASIC Compiler Commands 


Command Description 

SCRATCH Erases the current program and any loaded object modules. 
SEQUENCE Generates line numbers for input text. 

SET Specifies default values for compiler command qualifiers. 
SHOW Displays the current default compiler qualifiers. 

UNSAVE Deletes a specified file. 


The following sections describe these compiler commands. For more 
detailed information, see the VAX BASIC Reference Manual. 


3.5.1 Entering Comments 


VAX BASIC allows you to enter comments into the BASIC environment 
by specifying an exclamation point. Any text that follows the exclamation 
point (!) is treated as a comment. For example: 


$ TYPE build_special.com 

$ SET VERIFY 

$ BASIC 

t+ 

! Set the compilation unit options by uncommenting 
! the appropriate ones 

1- 


!SET LIST 
SET WORD 

SET DEBUG 

t+ 

! Get the source module. 
{- 

OLD SPECIAL 
I+ 

! Compile it. 
t- 

COMPILE 

1+ 

! All done. 
!- 


EXIT 
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3.5.2 Entering DCL Commands 


You can enter a DCL command while in the environment by preceding it 
with a dollar sign ($). VAX BASIC passes the command to the DCL for 
execution. The program currently in memory does not change. 


VAX BASIC starts a subprocess to execute the command, and the com- 
mand executes in the context of that subprocess. This can sometimes 
produce unexpected results. For example, a $ SET DEFAULT command 
typed in the BASIC environment sets the default for the subprocess but 
not for the process in which VAX BASIC executes. The newly set default 
exists only until control returns to VAX BASIC. 


3.5.3 The APPEND Command 


The APPEND command merges a VAX BASIC source program with 

the program currently in memory. The program in memory must be a 
VAX BASIC source program that has been placed in memory with the 
OLD command and entered in the environment. The program must also 
contain at least one line number. 


If both programs contain a line with the same number, the appended 
program line replaces the current program line. 


If you type APPEND without specifying a file name, VAX BASIC prompts 
with: 
Append file name-- 


You should respond with a file name. If you respond by typing the 
RETURN key, VAX BASIC searches for a file called NONAME with the 
default file type of BAS. If the compiler cannot find the file, it signals an 
error. 


The APPEND command does not change the name of the program in 
memory. 
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3.5.4 The ASSIGN Command 


The ASSIGN command equates a logical name to a complete file specifica- 
tion, a device, or another logical name. 


If the logical name translates to a device name and will be used in place of 
a device name in a file specification, terminate the equivalence name with 
a colon. 


This example uses the ASSIGN command to make the system HELP 
library available from within VAX BASIC: 

Ready 

ASSIGN SYS$HELP:HELPLIB HLP$LIBRARY 

The ASSIGN command does not support search lists. To assign a logical 
name to a search list from within the environment, use the $ system- 


command to execute the DCL command ASSIGN with the /JOB qualifier. 
For example: 


$ASSIGN/JOB DUAO: [MR.X] ,DUAO: [MR.Y] TWO$DIRECTORIES: 


3.5.5 The COMPILE Command 


When you compile a program in the BASIC environment, there are three 
levels at which you can specify options for the compiler: 


e You can accept the defaults of the BASIC environment as options 


e You can specify options with qualifiers to the COMPILE or SET 
command 


e You can specify options in the source program with the OPTION 
statement 


The COMPILE command creates an object module from a source program 
in memory. You can control the compilation of your program with the 
COMPILE command and its qualifiers. These qualifiers duplicate many of 
the qualifiers available to the DCL command BASIC. You can abbreviate 
all COMPILE qualifiers to four letters. For example, you can compile a 
program currently in memory and specify the creation of a listing file: 


COMPILE/LIST 
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The following two commands both specify that a listing file should be 
created. Note that the SET command sets a particular default until you 
leave the BASIC environment or until you specify a different default 
for that value, whereas the qualifiers to the COMPILE command set the 
defaults only for that particular compilation. 


SET/LIST 
COMPILE/LIST 
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If you do not specify any qualifiers with the SET command, VAX BASIC 
resets the defaults to the values that were in effect when you entered the 
BASIC environment. 


The qualifiers to the COMPILE command are listed below. Note that you 
can also use many of these qualifiers with the SET command to establish 
these compiler options. The qualifiers are described fully in the VAX 
BASIC Reference Manual. 


The /[NOJANSI_STANDARD qualifier causes VAX BASIC to 
compile the program according to ANSI Minimal BASIC rules and 
to flag statements that do not conform to the ANSI Minimal BASIC 
standard. The default is /NOANSI_STANDARD. 


The /[NOJAUDIT qualifier causes VAX BASIC to include a history 
entry in the Common Data Dictionary (CDD) data base when a CDD 
definition is extracted. The default is /NOAUDIT. 


The /[NO]JBOUNDS_CHECK qualifier causes VAX BASIC to perform 
range checks on array subscripts. That is, it checks that all array 
references are to addresses within the array boundaries. The default is 
/BOUNDS_CHECK=(BOUNDS, OVERFLOW). 


The /BYTE qualifier specifies that integers not explicitly typed with 
a data type keyword use 8 bits of storage, which lets you use integer 
values between -128 and 127. The default is 
/INTEGER_—SIZE=LONG. 


The /[NO]CROSS_REFERENCE[=[NO]KEYWORDS] qualifier 
causes VAX BASIC to generate a cross-reference listing. If you specify 
KEYWORDS, VAX BASIC provides a cross-reference list of VAX 
BASIC keywords. If you specify /CROSS_REFERENCE, the default is 
/CROSS_REFERENCE=NOKEYWORDS. The default is 
/NOCROSS_REFERENCE. 


The /[NO]DEBUG qualifier provides the debugger with local symbol 
definitions for program variables, constants, line numbers, and labels. 
The default is /DEBUG=(TRACEBACK, NOSYMBOLS). 


The /DECIMAL _SIZE qualifier specifies the default size and preci- 
sion for all DECIMAL data not explicitly assigned size and precision 
in the program. You specify the total number of digits (d) and the 
number of digits to the right of the decimal point (s). VAX BASIC sig- 
nals the error “Decimal error or overflow” (ERR=181) when DECIMAL 
values are outside the range specified with this qualifier. The default 
is /DECIMAL _SIZE=(15,2). 
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¢ The /DOUBLE qualifier specifies that floating point data use 64 bits 
of storage in D_float format, which lets you use floating-point values 
in the range 2.9 * 10—°? to 1.7 * 10°8 and with up to 16 digits of 
precision. The default is /REAL—SIZE=SINGLE. 


¢ The /[NO]JFLAG|-({NO]BP2COMPATIBILITY, [NOJDECLINING)] 
qualifier causes VAX BASIC to issue informational messages when 
your program includes statements that are not compatible with 
the functionality you specify. You can specify a flag for BASIC- 
PLUS-2, and declining VAX BASIC language features. The default is 
/NOFLAG. 


¢ The /GFLOAT qualifier specifies that floating-point data use 64 bits 
of storage in G_float format, which lets you use floating-point values 
in the range 5.6 * 10-38 to 9.0 * 10°°? and with up to 15 digits of 
precision. The default is /REAL—SIZE=SINGLE. 


e The /HFLOAT qualifier specifies that floating-point data use 128 bits 
of storage in H_float format, which lets you use floating-point values 
in the range 8.4 * 10-499 to 5.9 * 104° and with up to 33 digits of 
precision. The default is /REAL—SIZE=SINGLE. 


e The /[NO]LINES qualifier enables the executing program to report 
the line number of statements causing errors and to use the RESUME 
statement without specifying a line number. The default is /LINES. 


e The /{[NO]LIST qualifier creates a program listing with a default file 
type of LIS. The default is /NOLIST. 


e The /LONG qualifier specifies that untyped integers use 32 bits of 
storage, which lets you use integer values between -2147483648 and 
2147483647. The default is /INTEGER—SIZE=LONG. 


e The /[NOJMACHINE—CODE qualifier includes the compiler- 
generated assembly code listing. The default is 
/NOMACHINE_CODE. 


e The /[NOJOBJECT qualifier generates a linkable object module. This 
object module has the same file name as the VAX BASIC source 
program and a default file type of OBJ. The default is /OBJECT. 


¢ The /[NOJOVERFLOW[=((NOJINTEGER, [NO]DECIMAL)] qualifier 
enables the detection of arithmetic overflow on integer or packed 
decimal data. If you do not supply a value, OVERFLOW affects both 
data types. The default is /OVERFLOW=(INTEGER,DECIMAL). 

e The /[NOJROUND qualifier specifies whether VAX BASIC rounds or 
truncates packed decimal numbers. The default is /NOROUND. 
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The /[NO]SETUP qualifier causes VAX BASIC to optimize the ex- 

ecutable image by omitting certain calls to the Run-Time Library at 
the start and end of each program unit. Note that variables are not 
initialized when /NOSETUP is in effect. The default is /SETUP. 


The /[NOJSHOW qualifier allows you to specify what VAX BASIC 
should include in the listing file. For a list of items you can include 
in the listing file, see the VAX BASIC Reference Manual. The default is 
/SHOW. 


The /SINGLE qualifier specifies that floating-point data use 32 bits 
of storage, which lets you use floating-point values in the range 2.9 * 
10-*° to 1.7 * 10°8 and with up to 6 digits of precision. The default is 
/REAL_SIZE=SINGLE. 


The /[NOJSYNTAX—CHECK qualifier enables line-by-line syntax 
checking. Because VAX BASIC automatically performs syntax checking 
when you compile a program, you normally use /SYNTAX CHECK 
with the SET command to enable line-by-line syntax checking while 
you are typing program lines. The default is /NOSYNTAX CHECK. 


The /[NOJTRACEBACK qualifier provides line numbers for the 
debugger and error reporter so they can translate virtual addresses 
into source program module names and line numbers. The default is 
/ TRACEBACK. 


The /TYPE_DEFAULT qualifier allows you to specify the default 
data type for all data not explicitly typed in your program. See the 
VAX BASIC Reference Manual for a list of data types you can include. 
The default is /TYPE_DEFAULT=REAL. 


The /VARIANT=value qualifier provides a value to be tested in 
conditional compilations. The default is /VARIANT=0. 


The /[NOJWARNINGS[={[NO]WARNINGS, 
[NO]INFORMATIONALS] qualifier tells VAX BASIC whether to dis- 
play warning or informational error messages. /NOWARNINGS 
means that VAX BASIC does not display any informational 

or warning errors. The default is /WARNINGS=WARNINGS, 
INFORMATIONALS. 


The /WORD qualifier specifies that all integer data not explicitly 
typed use 16 bits of storage, which lets you use integer values in the 
range -32768 to 32767. The default is /INTEGER—SIZE=LONG. 
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If you use these qualifiers with the COMPILE command, the BASIC en- 
vironment default values remain the same, but your program is compiled 
using the specified defaults. When you use these qualifiers with the SET 
command, you set the defaults for the period you are within the BASIC 
environment. You can also set compiler options from inside the source 
program by using the OPTION statement. See the VAX BASIC Reference 
Manual for more information on the OPTION statement. 


3.5.6 The CONTINUE Command 


The CONTINUE command resumes program execution after VAX BASIC 
encounters a STOP statement or a CTRL/C. After a STOP statement 

or a CTRL/C is encountered in the BASIC environment, you can enter 
immediate mode statements to display or change program variables. Then, 
type CONTINUE to resume execution with the new values. 


3.5.7 The DELETE Command 


The DELETE command removes a specified line or lines from the source 
program currently in memory. If you separate line numbers with commas, 
VAX BASIC deletes only the specified program lines. If you separate line 
numbers with a hyphen (-), VAX BASIC deletes the specified program 
lines and all program lines between them. For example: 


DELETE 10 Removes line 10 from the program 

DELETE 50, 100 Removes lines 50 and 100 from the program 

DELETE 50, 100-190 Removes line 50 and lines 100 through 190 from the 
program 


If you do not specify a line number, the DELETE command is ignored. 


3.5.8 The EDIT Command 


The EDIT command replaces text in the current program with text you 
supply in the command. If you type EDIT with no argument, VAX BASIC 
invokes a text editor and reads the current program into the editor’s buffer. 
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The following are examples of editing in line mode: 


EDIT 100 /LEFT$/RIGHT$/ Replaces the first occurrence of LEFT$ with 
RIGHT$ on line 100. 


EDIT Invokes the default editor and reads the current 
program into the editor’s buffer. 

EDIT 2000 Lists line 2000 (line 2000 becomes the default 
EDIT line). 


EDIT 30 /LEFT$/RIGHT$ /,3 Starts the search on the third text line of 
program line 30 and replaces the first occurrence 
of LEFT$ with RIGHTS. 

EDIT 300/LEFT$//2 Removes the second occurrence of the string 
LEFT$ from line 300. Note that you must 
specify delimiters around the null replacement 
string. Otherwise, the EDIT command would 
replace the first occurrence of LEFT$ with 2. 


Entering EDIT with no argument causes VAX BASIC to save your program 
temporarily in a file called BASEDITMP.BAS. The editor is then invoked 
and you can edit the program in the usual manner. Exiting from the editor 
causes the changed program to become the new current program. VAX 
BASIC then displays the Ready prompt. Note that VAX BASIC deletes all 
versions of BASEDITMP.BAS when control returns from the editor. 


VAX BASIC supports the following callable text editors: 

e VAX EDT 

e VAX Text Processing Utility (VAXTPU) 

e VAX Language-Sensitive Editor (LSE) 

The default editor for VAX BASIC is EDT. In DCL, you or your sys- 
tem manager can override this default by defining the logical name 


BASIC$EDIT. To find out if a system assignment exists, enter the following 
DCL command: 


$ SHOW LOGICAL BASIC$EDIT 


The name you assign to BASIC$EDIT must be in the form nnn$EDIT, 
where the characters nnn represent the acronym for the editor. For 
example, you can assign LSE to be the default editor with the following 
command: 


$ ASSIGN "LSE$EDIT" BASIC$EDIT 
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If the translation of BASIC$EDIT does not conform to nnn$EDIT, VAX 

BASIC creates a temporary file containing your source code and spawns 
a subprocess. VAX BASIC passes the translation of BASIC$EDIT to the 
subprocess. 


3.5.9 The EXIT Command 


The EXIT command clears memory and returns control to DCL command 
level. If you modify a program and issue the EXIT command before you 
copy it to disk with the SAVE or REPLACE command, VAX BASIC signals 
“Unsaved change has been made, CTRL/Z or EXIT to exit”. This message 
warns you that any changes will be lost if you do not save the program. 
You can then store the program or retype the EXIT command (or press 
CTRL/Z) to exit from VAX BASIC. 


3.5.10 The HELP Command 


The HELP command lets you display the contents of the VAX BASIC 
HELP library on the terminal. Entering HELP causes the HELP facility 

to display a long list of VAX BASIC commands and language topics for 
which there is help available. You are then prompted to name a command 
or topic with the following prompt: 


Topic? 


To obtain help on the environment commands, you can type COMMANDS 
at the “Topic?” prompt. A list of commands is displayed on your terminal 
followed by the prompt “COMMANDS Subtopic?”. When you type a 
command name in response to this prompt, the HELP facility displays the 
following: 


e An explanation of the command’s purpose 
e An example of its use 
e A list of any further subtopics available 


You can also display help text for VAX BASIC errors. The help texts 
for the VAX BASIC error messages are grouped under two categories: 
compile-time errors and run-time errors. A run-time error refers to any 
error that occurs during program execution. All other errors are referred 
to as compile-time errors. Typing HELP RUN displays a list of the 3- 
to 9-character error mnemonics for the VAX BASIC list of run-time 


3-20 Developing Programs in the BASIC Environment 


errors, and typing HELP COMPILE displays a list of the 3- to 9-character 
compile-time error mnemonics. 


For example, suppose your program invokes a user-defined DEF function 
with a null argument. This causes VAX BASIC to signal “Actual argument 
must be specified”. The actual error message looks like this: 


%BASIC-E-ACTARGMUS, actual argument must be specified 
You display the help text by typing: 

HELP COMPILE ACTARGMUS 

The following text is then displayed on your screen. 


ACTARGMUS 


ERROR - A DEF function reference contains a null argument, for 
example FNA(1,,2). Specify all arguments when referencing a DEF 
function. 


You can access run-time errors with either the mnemonic or the error 
number. You specify the error number with the letters “ERR” followed 
by the error number. For example, you can display the HELP text for the 
end-of-file error by using the mnemonic as shown: 


HELP RUN ENDFILDEV 
If you know only the error number, type: 
HELP RUN ERR11 


VAX BASIC displays the appropriate mnemonic for that error. 


3.5.11 The IDENTIFY Command 


The IDENTIFY command prints a header containing the VAX BASIC 
compiler name and version number. For example: 


IDENTIFY 
VAX BASIC V3.0 
Ready 
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3.5.12 The LIST and LISTNH Commands 


The LIST and LISTNH commands display a specified line or lines. If 
you type LIST or LISTNH without specifying line numbers, VAX BASIC 
displays a copy of the source program currently in memory, in ascending 
line number order. 


The LIST command prints a header displaying the program name and the 
current time and date before displaying the specified lines. The LISTNH 
command suppresses the header information and prints the specified lines 
only. For example: 


LIST 10 Displays header information, then displays line 10. 
LISTNH 50, 100 Displays lines 50 and 100. 


LIST 50, 90, 100-190 Displays header information, then displays lines 50, 90, 
and 100 through 190. 


3.5.13 The LOAD Command 


The LOAD command makes an object module available for execution with 
the RUN command. You can load only object files created by VAX BASIC. 


The LOAD command accepts multiple device, directory, and file specifi- 
cations. The LOAD command deletes all previously loaded object files; 
therefore, to load several files at the same time, you must separate the 
file specifications with plus signs. Multiple file specifications separated 
with commas cause each file to be loaded separately, thereby deleting the 
previously loaded file. 


If you do not specify any file specification, the LOAD command erases 
any previously loaded object files. 


LOAD OLD1 + OLD2 + OLD3 
Ready 


RUN 
The above example loads the files OLD1.OBJ, OLD2.OBJ, and OLD3.OBJ 
for execution. These object files are not linked with the current program 


or executed until you issue the RUN command. Therefore, run-time errors 
in the loaded modules are not detected until you execute the program. 
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Each device and directory specification applies to all following file specifi- 
cations until you specify a new directory or device. For example: 


LOAD DUA1: [SMITH] PROG3+ [JONES] PROG4+DUA2 : PROGE 
This command loads three object files: 


e PROG3 from the directory SMITH on the device DUAI: 
e PROG4 from the directory JONES on DUAI: 
¢ PROGS from the directory JONES on DUA2: 


3.5.14 The LOCK Command 


The LOCK command changes default values for COMPILE command 
qualifiers. It is equivalent to the SET command. The following command 
specifies that all subsequent compilations use double-precision floating- 
point numbers as the default. You can use any valid COMPILE command 
qualifier as an argument to LOCK. 


LOCK /DOUBLE 
Ready 


3.5.15 The NEW Command 


The NEW command clears the memory and assigns a name to a program 
to be entered. The following command assigns the name PROGI to the 
program. You can then enter program lines. 


NEW PROG1 
If you do not specify a name, VAX BASIC issues the following prompt: 
New file name-- 


You should respond with a name. If you press the RETURN key in 
response to the prompt, VAX BASIC assigns the name NONAME. 
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3.5.16 The OLD Command 


The OLD command brings a previously created VAX BASIC source file 
into memory. The following command reads PROG1.BAS into memory. 


OLD PROG1 


If you do not specify a file name, VAX BASIC issues the prompt: 


Old file name-- 


You should respond with a file name. If you do not specify a file type, 
VAX BASIC reads a file with the specified file name and the default file 
type. If you press the RETURN key in response to the prompt, VAX 
BASIC searches for a file with the default file name and default a type: 
NONAME.BAS. 


3.9.17 The RENAME Command 


_ The RENAME command assigns a new name to the program currently in 
memory. For example, the following command sequence brings a program 
named PROGI1 into memory and changes its name and directory: 

OLD [KELLY] PROG1 
Ready 


RENAME [MCKAY. BASIC] PROG2 


The name of the program is changed to PROG2. If you perform a 
REPLACE operation, PROG2 is copied to the subdirectory [MCKAY.BASIC] 
instead of [KELLY]. The remaining portion of the specification is un- 
changed. If you do not specify a program name, VAX BASIC renames the 
current program NONAME. 
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3.5.18 The REPLACE Command 


The REPLACE command writes the program in memory to a specified 
device. The REPLACE command always writes a copy of the current pro- 
gram back to disk. It replaces it using the file specification specified in the 
last OLD command. Part or all of this file specification can be overwritten 
with the RENAME command; whatever parts are not specifically changed 
remain the same. RENAME is similar to SAVE except that while SAVE 
copies the current program to the default directory, REPLACE copies the 
current program to the location specified in the program’s current file 
specification. 


After execution of a REPLACE command, VAX BASIC issues an informa- 
tional message confirming the file specification. 


3.5.19 The RESEQUENCE Command 


The RESEQUENCE command allows you to resequence the line numbers 
of the program currently in memory. VAX BASIC also changes all refer- 
ences to the old line numbers so they reference the new line numbers. 
You can specify a starting line number and a value by which to increase 
each subsequent line number. The following command resequences the 
line numbers from 10 to 10000, making the first line number 100 and 
increasing each subsequent line number by 20: 


RESEQUENCE 10~10000 100 STEP 20 


The RESEQUENCE command is not allowed on programs without line 
numbers. 


3.5.20 The RUN and RUNNH Commands 


The RUN command executes a program. This program can be any one of 
the following: 
e The current program 


¢ One or more object modules placed in memory with the LOAD 
command 


e A combination of the first two 
e A specified VAX BASIC source program 
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If you do not supply an alternative file specification, VAX BASIC executes 
the program in memory. 


Ready 


OLD 
Old file name--PROG1 
Ready 


RUN 


The RUN command compiles, links, and executes PROG1. It prints a 
header displaying the program name and the current date and time. To 
execute a program without displaying this header, type RUNNH. 


The RUN command does not create an object module file or a list file. It 
uses whatever qualifiers have been set. The following qualifiers are always 
in effect for the RUN and RUNNH commands: 


e NOCROSS 

¢ NODEBUG 

¢ = NOLIST 

e NOMACHINE 
e NOOBJECT 

e SETUP 


The RUN command can invoke only VAX BASIC procedures and other 
procedures that reside in shareable image libraries. See Chapter 22 for 
more information on creating shareable images. 


3.5.21 The SAVE Command 


The SAVE command copies a VAX BASIC source program from memory 
to a file. You can specify a storage device, a file name, and a file type in 
the SAVE file-spec. For example, if you type the following program, a 
SAVE command causes VAX BASIC to arrange the program in ascending 
line number order and copy it to a file on MTA1:, in the current default 
directory with file name TEST and the default file type of BAS. 
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Example 


10 REM THIS IS A TEST 
30 PRINT “THIS IS A TEST" 
SAVE MTA1: TEST. BBB 


VAX BASIC saves the program on magnetic tape MTAI1: in the current 
default directory with a file name of TEST and a file type of BBB. If the 
program in memory has no name and you issue the SAVE command with 
no argument, VAX BASIC copies the program to a file named NONAME 
with the default file type in your current default device and directory. 
Note that if you perform a RENAME operation, before you issue the 
SAVE command followed by no argument, VAX BASIC still copies the 
program to the current default directory. 


3.5.22 The SCALE Command 


The SCALE command can overcome accumulated round-off errors by 
multiplying double-precision floating-point values by 10 raised to the 
specified scale factor before storing them. 


3.5.23 The SCRATCH Command 


The SCRATCH command clears memory by doing one of the following: 


e = Resetting the program name to NONAME 
e Removing any object files previously loaded with the LOAD command 
¢ Removing the source file currently in memory 


3.5.24 The SEQUENCE Command 


The SEQUENCE command automatically generates line numbers for 
input text. After a SEQUENCE command, VAX BASIC prompts with a 
line number and prompts again after each source line you enter. If you 
press CTRL/Z (either in response to the line number prompt or at the 
end of a program line), VAX BASIC stops prompting and you can enter 
source text in the normal way. If you specify a starting line number that 
already contains a statement, VAX BASIC signals “Attempt to sequence 
over existing statement” and returns to normal input mode. 


Note that the SEQUENCE command is not allowed on programs without 
line numbers. 
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3.5.25 The SET Command 


The SET command specifies defaults for compiler command qualifiers. For 


example: 
SET /SINGLE 
Ready 


This command makes /SINGLE the default for the COMPILE or RUN 
command, thereby making SINGLE the default data type for all untyped 
values. Typing SET with no arguments resets the defaults to their state 
when you entered into the BASIC environment. 


For a full list of options, see the COMPILE command. 


3.5.26 The SHOW Command 


The SHOW command displays the current default qualifiers and user 


libraries. 


SHOW 


VAX BASIC V3.0 Current Environment Status 22-JUN-1986 10:12:12.05 


DEFAULT DATA TYPE INFORMATION: 
Data type : REAL 
Real size : SINGLE 
Integer size : LONG 
Decimal size : (15,2) 
Scale factor : 0 
NO Round decimal numbers 


COMPILATION QUALIFIERS IN EFFECT: 
Object file 
Overflow check integers 
NO Overflow check decimal numbers 
Bounds checking 
NO Syntax checking 
Lines 
Variant : 0 
NO Warnings 
NO Informationals 
Setup 
Object Libraries : NONE 
Ready 
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LISTING FILE INFORMATION INCLUDES: 


Source 
NO Cross reference 
CDD Definitions 
Environment 
NO Override of %NOLIST 
NO Machine code 
Map 


INCLUDE files 


FLAGGERS : 
Declining features 
NO BASIC PLUS 2 subset 


DEBUG INFORMATION: 
Traceback records 
NO Debug symbol records 


This DEFAULT DATA TYPE INFORMATION display gives you the 
following information: 


The default data type is REAL. 


The default size for floating-point numbers is SINGLE, the default size 
for integers is LONG, and the default size for packed decimal numbers 
is (15,2). 


There is no scale factor in effect. 
Packed decimal numbers are truncated rather than rounded. 


The LISTING FILE INFORMATION display tells you which parts of the 
program listing are included if you create a compilation listing: 


The source program is listed. 
No cross-reference information is listed. 
CDD definitions are displayed as RECORD statements. 


The qualifiers in effect when the program was compiled are listed. 
This means that the program listing contains the equivalent of this 
SHOW command. 


The %NOLIST compiler directive is not overridden. 
No compiler-generated machine code is listed. 


An allocation map is listed. This contains the sizes and offsets of any 
variables. 


Files accessed with the %INCLUDE directive are listed. 


The COMPILATION QUALIFIERS IN EFFECT section gives you the 
following information: 


An object file is produced. 

Overflow checking for integers is enabled. 

Overflow checking for packed decimal numbers is disabled. 

Bounds checking is enabled. 

Line-by-line syntax checking is disabled. 

Line number information is included in the object file. 

The VARIANT value is zero. 

No warning or informational error messages are displayed. 

VAX BASIC performs normal initialization calls at run time (SETUP). 
No user-supplied object module libraries are searched. 


Developing Programs in the BASIC Environment 3-29 


The FLAGGERS section gives you the following information: 


e Declining features are reported. 
e BP2 compatibility issues are not reported. 


The DEBUG INFORMATION section gives you the following information: 


e Traceback information is included in the object module. 
¢ No debug records are included in the object module. This means you 
cannot access program symbols with the VAX/VMS Debugger. 


See Chapter 22 for more information about user libraries. 


3.5.27 The UNSAVE Command 


The UNSAVE command deletes the specified version of a file from disk. 
If you do not specify a file, UNSAVE deletes the disk file associated with 
the program currently in memory. If you do not specify a version number, 
UNSAVE deletes the newest version. For example: 


OLD PROG1 
Ready 
UNSAVE 
Ready 


The OLD command copies a program named PROG1.BAS from disk to 
memory. The UNSAVE command deletes the program from disk. 


You can delete a VAX BASIC source program other than the one in 
memory by specifying the program name. The following command 
deletes the most recent version of the file PROG2.BAS. 


UNSAVE PROG2 


To delete a file other than a source program, specify the file name and file 
type. The following command deletes the newest version of the object 
module generated from the compilation of PROG2. 


UNSAVE PROG2.0BJ 
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Chapter 4 


Developing VAX BASIC Programs at DCL 
Command Level 


The process of developing a VAX BASIC program involves four steps: 
creating, compiling, linking, and running. You accomplish each of these 
steps using DCL commands. This chapter describes how to create, com- 
pile, link, and run a VAX BASIC program. 


4.1 Creating a VAX BASIC Program 


To create and modify a VAX BASIC program, you must invoke a text 
editor. VAX/VMS provides you with two text editors: VAX EDT (EDT) 
and the VAX Text Processing Utility (VAXTPU). You may also have other 
editors that are supported on your system, such as the VAX Language- 
Sensitive Editor (LSE). The following sections describe briefly how to use 
both VAX EDT and VAXTPU. 


4.1.1 Using VAX EDT 


EDT is an interactive general-purpose text editor that offers three editing 
modes: keypad, nokeypad, and line. Both keypad and nokeypad modes 
are screen editors. Keypad mode uses the numeric keypad that appears 

to the right of your main keyboard. With nokeypad mode, you enter 
commands on a command line, which EDT processes when you press 
RETURN. Line mode focuses on the line as the basic unit of text. The 
appearance of a line mode asterisk prompt (*) indicates that you can enter 
a line mode command. When you begin your editing session, editing in 
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line mode is the default. Unlike line mode, keypad mode and nokeypad 
mode continuously display the contents of the file on your screen. 


The following command line invokes the EDT editor and creates the file, 
PROG_1.BAS. 


$ EDIT/EDT PROG_1.BAS 


To change from line mode to keypad mode, enter the CHANGE command 
at the asterisk prompt. To return to line mode from keypad mode, press 
CTRL/Z. To change from line mode to nokeypad mode, enter the SET 
NOKEYPAD command and then enter the CHANGE command. 


If you are in the middle of an editing session and your system fails, you 
can recover your edits by reentering the EDIT command followed by the 
/RECOVER qualifier. EDT recreates your last editing session on your 
screen up to the point where it was interrupted. It uses the contents of a 
journal file that is maintained during the editing session. 


EDT provides an online HELP facility that you can access during an 
editing session. In line mode, you can enter the HELP command. EDT 
displays general information on EDT as well as detailed information on 
both line mode editing and nokeypad mode editing. In keypad mode, you 
can press the HELP key or the PF2 key. EDT displays a keypad diagram 
on your terminal screen, and a list of keypad editing keys. For help on a 
specific keypad function, press the key you want help on. 


For details on how to use the EDT editor, see the VAX EDT Reference 
Manual. 


4.1.2 Using VAXTPU 


The VAX Text Processing Utility (VAXTPU) is a high-performance, pro- 
grammable editor. With VAXTPU, you can use one of two editing inter- 
faces to edit your VAX BASIC programs: the Extensible VAX Editor (EVE) 
and the VAXTPU EDT Keypad Emulator. You can also create your own 
interfaces. The following sections briefly describe how to use the EVE 
interface and the EDT Keypad Emulator interface. 
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4.1.2.1 


The EVE Interface 


The EVE editor is efficient and easy to use. You can execute common 
editing functions by using the EVE keypad, or execute more advanced 
functions by entering commands on the EVE command line. The follow- 
ing command line invokes the EVE editor and creates the file, 
PROG_1.BAS. 


$ EDIT/TPU PROG_1.BAS 


You can define a global symbol for the EDIT/TPU command by placing 
a symbol definition in your LOGIN.COM file. For more information on 
defining global symbols, see Chapter 2. 


Like EDT, VAXTPU provides you with an online HELP facility that you 
can access during your editing session. It also provides you with a journal 
facility. Unlike EDT, VAXTPU provides you with multiple windows. This 
feature allows you to view two files on your screen at the same time. 
VAXTPU also provides you with other advanced features. 


For more information on using the features of EVE, see the User’s Guide to 
EVE. 


4.1.2.2 The EDT Keypad Emulator Interface 


The EDT Keypad Emulator interface provides all of the functions asso- 
ciated with EDT and uses the same keys to perform each function. To 
access the EDT Keypad Emulator, enter the following command line: 


$ EDIT/TPU/SECTION=EDTSECINI .GBL 


To minimize the number of characters you must enter each time you 
invoke the EDT Keypad Emulator, you can define a global symbol for the 
command line and place it in your LOGIN.COM file. See Chapter 2 for 
more information on defining global symbols. For details on how to use 
the EDT Keypad Emulator, see the VAXTPU EDT Keypad Emulator Quick 
Reference Guide. 
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4.2 Compiling a VAX BASIC Program 


The primary functions of the VAX BASIC compiler are to 


e Detect errors in your source program 

e Generate any appropriate error messages 

e Generate machine language instructions from the source statements 

¢ Group these language instructions into an object module for the linker 


To invoke the VAX BASIC compiler, you use the DCL command BASIC. 
With the BASIC command, you can specify command qualifiers. The next 
two sections discuss in detail the BASIC command as well as all of the 
command qualifiers available with the command. 


4.2.1 The BASIC Command 


When you compile your source program, use the BASIC command, which 
has the form 


BASIC [/qualifier...][ file-spec [/qualifier...]],... 


/qualifier 

The name of a qualifier that indicates a specific action to be performed by 
the compiler on all files or specific files listed. When a qualifier appears 
directly after the BASIC command, it affects all files listed. 


file-spec 

Indicates the name of the input source file that contains the program or 
module to be compiled. You are not required to specify a file extension; 
the VAX BASIC compiler assumes the file to be of the default file type, 
BAS. 


If you enter the BASIC command with no parameters, you will enter the 
BASIC environment. For more information on the BASIC environment, 
see Chapter 3. 


Most of the command qualifiers to the BASIC command affect all files 
specified in the command line, no matter where the qualifiers are placed; 
these are called global qualifiers. However, the qualifiers /LISTING, 
/OBJECT, and /DIAGNOSTICS are positional qualifiers; that is, depending 
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on their position in the command line, they can affect all or only some of 
the specified files. The rules for positional qualifiers are as follows: 


e If the positional qualifier is located directly following the command 
name, it affects all the specified files. 


e If the file specifications are separated by commas, then any positional 
qualifier directly following a file specification affects only that file. 


e If the file specifications are separated by plus signs, then any positional 
qualifier directly following a list of file specifications affects only the 
resulting appended file. 


¢ The rightmost qualifier overrides any conflicting qualifier previously 
specified in the command line. 


The placement of these positional qualifiers causes VAX BASIC to produce 
or not produce listing files, object files, and diagnostics files. For example: 


$ BASIC/LIST/OBJ PROG1/NOOBJ/DIAG , PROG2+PROG3/NOLIST 
This command does the following: 


¢ Compiles PROG1 and produces a listing file called PROG1.LIS 
e Produces no object file for PROG1 
e Produces a diagnostics file for PROG1 called PROG1.DIA 


e Appends PROG2 and PROG3 for compilation, producing a temporary 
source file called PROG2 


e Compiles the new PROG2 and produces an object file called 
PROG2.OBJ 


e Produces no listing file for the new PROG2 


Because VAX BASIC appends source files that are separated by plus signs, 
you should make sure that these files contain line numbers. VAX BASIC 
does not allow you to append programs without line numbers. You must 
also make sure that these files do not contain duplicate line numbers. If 
there are duplicate line numbers, VAX BASIC replaces the first instance of 
that numbered line with the second. 


You should be careful when using positional qualifiers inside a list of files 
separated with plus signs, because a positional qualifier specified for a 
single file affects all the files in that list. In the following example, the 
/NOOBJ positional qualifier appears to apply only to PROG2. However, 
since VAX BASIC appends PROG1, PROG2, and PROG3 to form one file 
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called PROG1, the /NOOBJ qualifier applies to the new PROG] and 
VAX BASIC does not produce an object module. 


BASIC PROG1+PROG2/NO0BJ+PROG3 


4.2.2 BASIC Command Qualifiers 


The following list represents all of the command qualifiers and their 
defaults available with the DCL command BASIC. The SINGLE, DOUBLE, 
WORD, and LONG qualifiers are supported for compatibility with older 
versions of VAX BASIC. However, DIGITAL recommends that you use the 
/TYPE_DEFAULT, /INTEGER_SIZE, /REAL SIZE, and 
/DECIMAL~_SIZE qualifiers to set the default data type and size. A 
description of each qualifier follows the list. 


Command Qualifier 
/[NOJANALYSIS_DATA [ = file-spec ] 
/[NOJANSI_STANDARD 

/[NOJAUDIT [ = text-entry ] 
/[NO]CHECK [ = (check-clause,...) ] 
/[NO]CROSS_REF [ = [NO]JKEYWORDS ] 
/{NO]DEBUG [ = (debug-clause.,...) ] 
/DECIMAL _SIZE = (d,s) 
/[NO]DEPENDENCY_DATA 
/[NO]DIAGNOSTICS [ = file-spec] 
/DOUBLE 

/[NO]FLAG [ = ( flag-clause,... ) ] 


/INTEGER_SIZE = data-type 
/{(NO]LINES 
/{NO]LISTING [ = file-spec ] 


/LONG 

/[NO]JMACHINE_CODE 
/[NOJOBJECT [ = file-spec | 
/[NOJOLD_VERSION=CDD_ARRAYS 
/REAL_SIZE = data-type 
/[NO]JROUND_DECIMAL 
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Default 

/NOANALYSIS_DATA 
/NOANSI_STANDARD 

/NOAUDIT 

/CHECK=(BOUNDS, OVERFLOW) 
/NOCROSS_REF 
/DEBUG=(TRACEBACK,NOSYMBOLS) 
/DECIMAL _SIZE=(15,2) 
/NODEPENDENCY_DATA 
/NODIAGNOSTICS 


/FLAG = (NODECLINING, 
NOBP2COMPATIBILIT Y) 

/INTEGER_SIZE = LONG 

/LINES 

/NOLISTING (from terminal) 

/LISTING (batch) 


/NOMACHINE_CODE 
/OBJECT 
/NOOLD_VERSION 
/REAL_SIZE = SINGLE 
/NOROUND_DECIMAL 
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/SINGLE 


/[NOJSYNTAX_CHECK /NOSYNTAX_CHECK 

/TYPE_DEFAULT = default-clause /TYPE_DEFAULT = REAL 

/VARIANT = int-const /VARIANT = 0 

/[NO]WARNINGS [ = ( warn-clause....) ] /WARNINGS = (INFORMATIONALS, 
WARNINGS) 

/WORD 


/[NOJANSI_STANDARD 

The /ANSI_STANDARD qualifier causes VAX BASIC to allow only 
statements valid for ANSI Minimal BASIC and to compile programs 
according to the ANSI Minimal BASIC rules. 


The /NOANSI_STANDARD qualifier causes VAX BASIC to allow exten- 
sions and implementation-defined features. 


The default is /NOANSI_STANDARD. See the VAX BASIC Reference 
Manual for more information about ANSI standard BASIC. 


_ | str-lit 
/[NOJAUDIT = { file-spec } 


The /AUDIT qualifier causes VAX BASIC to include a history entry in the 
CDD when extracting a CDD definition. You can specify either a string 
literal or a file specification with the /AUDIT qualifier. If you specify a 
string literal, VAX BASIC includes it as part of the history entry. If you 
specify a file specification, VAX BASIC includes up to the first 64 lines of 
the specified file. When you specify /AUDIT, VAX BASIC also includes 
the following information about the CDD record extraction in the history 
entry: 

e The name of the program module making the extraction 

e The time and date of the extraction 

e A note that access was made by way of a VAX BASIC program 

e A note that the access was an extraction 


e The username and UIC of the process accessing the CDD 


The /NOAUDIT qualifier causes VAX BASIC not to include a history entry 
in the CDD when extracting a CDD definition. 


The default is /NOAUDIT. 
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[NO]JBOUNDS 
/[NO]CHECK = [NOJOVERFLOW [=(INTEGER, DECIMAL)] 
ALL 


NONE 
The /CHECK qualifier causes VAX BASIC to test for arithmetic overflow 
and for array references outside array boundaries when the program 
executes. Specifying /CHECK=-NOBOUNDS means that your program 
is smaller and runs faster. However, no error is signaled for an array 
reference outside the bounds of an array. This means that the program 
may get a memory management or access violation error at run time. 
Therefore, this option should be used only for programs that have been 
thoroughly debugged and whose execution time is critical. If you specify 
/ CHECK=OVERFLOW, overflow checking is enabled for both integers and 
packed decimal numbers. Similarly, specifying /CHECK=-NOOVERFLOW 
disables overflow checking for both types of numbers. 


The /NOCHECK qualifier causes VAX BASIC to not test for arithmetic 
overflow and for array references outside array boundaries when the 
program executes. 


/CHECK = ALL is the same as /CHECK = (BOUNDS, OVERFLOW). 
/CHECK = NONE is the same as /NOCHECK. 


The default is /CHECK = (BOUNDS, OVERFLOW). 


/[NOJCROSS_REFERENCE [= [NOJKEYWORDS ] 

The /CROSS_REFERENCE qualifier causes VAX BASIC to generate a 
cross-reference listing. The cross-reference list shows program symbols, 
their class, and the program lines in which they are referenced. /CROSS_ 
REFERENCE=KEYWORDS specifies that the cross-reference listing in- 
cludes all references to VAX BASIC keywords. If you specify /CROSS_ 
REFERENCE alone, the default is NOKEYWORDS. See Chapter 18 for 
more information on cross-reference listings. 


The /NOCROSS_REFERENCE qualifier specifies that no cross-reference 
listing be produced. 


The default is /NOCROSS_REFERENCE. 


[NO]SYMBOLS 
/[NO]DEBUG = INOHBACERAEK 


NONE 
The /DEBUG qualifier causes VAX BASIC to provide information for the 
VAX/VMS Debugger and the system run-time error traceback mechanism. 
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The default is /NOCROSS_REFERENCE. 


[NO]JSYMBOLS 
/[NO]DEBUG = [RO ITRACEBACK 


NONE 
The /DEBUG qualifier causes VAX BASIC to provide information for the 
VAX/VMS Debugger and the system run-time error traceback mechanism. 
Neither TRACEBACK nor SYMBOLS affects a program’s executable code. 
For more information on debugging, see Chapter 5. 


The /NODEBUG qualifier causes VAX BASIC to suppress information 
for the VAX/VMS Debugger and the system run-time error traceback 
mechanism. 


/DEBUG = ALL is the same as /DEBUG = (TRACEBACK, SYMBOLS). 
/DEBUG = NONE is the same as /NODEBUG. 


The default is /DEBUG = (TRACEBACK, NOSYMBOLS). 


/DECIMAL _SIZE = (d,s ) 

The /DECIMAL_SIZE qualifier lets you specify the default size for packed 
decimal data. You specify the total number of digits in the number and 
the number of digits to the right of the decimal point. 


/DECIMAL_SIZE = (15,2) is the default. This default decimal size applies 
to all decimal variables for which the total number of digits and digits 

to the right of the decimal point are not explicitly declared. See the 

VAX BASIC Reference Manual for more information about packed decimal 
numbers. 


/(NOJDEPENDENCY_DATA 

If you have CDD/Plus Version 4.0 installed on your system, and 

if your current CDD$DEFAULT is a CDO-format dictionary, the 
/DEPENDENCY_DATA qualifier generates a compiled module entity 
in the CDD$DEFAULT for each compilation unit. 


You must specify this qualifier if you want %INCLUDE %FROM %CDD 
and %REPORT %DEPENDENCY directives to establish dependency 
relationships. 


/NODEPENDENCY_DATA is the default. No compiled module entity is 
generated in this case. 
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A(NOJDIAGNOSTICS [= file-spec ] 

If you have the VAX Language-Sensitive Editor (LSE) installed on your 
system, you can use the /DIAGNOSTICS qualifier to create a diagnos- 
tics file containing compiler messages and diagnostic information. The 
diagnostics file is used by LSE to display diagnostic error messages and to 
position the cursor on the line and column where a source error exists. 


If you do not supply a file specification with the /DIAG qualifier, the di- 
agnostics file has the same name as its corresponding source file and a file 
type of DIA. All other file specification attributes depend on the placement 
of the qualifier in the command. See the VAX/VMS documentation set for 
more information. 


The /NODIAGNOSTICS qualifier specifies that no diagnostics file will be 
created. The default is /NODIAGNOSTICS. 


[NO]JBP2COMPATIBILITY 
[NO]DECLINING 

ALL 

NONE 

The /FLAG qualifier lets you specify whether VAX BASIC warns you 
about declining features and compatibility with PDP-11 BASIC-PLUS-2. 


The /NOFLAG qualifier causes VAX BASIC to not warn you about 
declining features and compatibility with PDP-11 BASIC-PLUS-2. 


/ FLAG = ALL is the same as 
/FLAG = (BP2COMPATIBILITY, DECLINING). 
/¥LAG = NONE is the same as /NOFLAG. 


The default is /FLAG = (NODECLINING, NOBP2COMPATIBILITY). 


/[NO]FLAG = 


BYTE 
/INTEGER_SIZE= < WORD 

LONG 
The /INTEGER_SIZE qualifier lets you specify the default size for integer 
data. 


The default is INTEGER—SIZE = LONG. The default integer size applies 
to all integer variables whose data type is not explicitly declared. See 
the VAX BASIC Reference Manual for more information about integer data 


types. 
/(NOJLINES 


The /LINES qualifier makes line number information available for the 
ERL function, the RESUME statement (with no target) and the VAX BASIC 
error reporter. If your program contains a RESUME statement with no 
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target, or a reference to the error-handling function ERL, the compiler 
overrides NOLINES and signals “ERL overrides NOLINE” or “RESUME 
overrides NOLINE”. Note that the VAX BASIC error reporting facility is 
separate from that of system traceback. 


The /NOLINES qualifier causes line number information to be unavailable 
for the ERL function, the RESUME statement (with no target) and the 
VAX BASIC error reporter. Specifying /NOLINES makes your program 
run faster and reduces program size (this eliminates five bytes of code and 
four bytes of data for each program line number). However, specifying 
/NOLINES causes the following restrictions to be in effect: 


e You cannot use RESUME without a line number 


e You cannot use the ERL function 
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Therefore, this option should be used only for programs that have been 
thoroughly debugged and whose execution time is critical. 


The default is /LINES. 


/A(NOJLISTING 
The /LISTING qualifier causes VAX BASIC to produce a source listing file. 


To produce a listing file with an explicit file specification, you must use 
the /LISTING qualifier in the form /LISTING = file-spec. Otherwise, the 
listing file has the same name as its corresponding source file and a file 
type of LIS. All other file specification attributes depend on the placement 
of the qualifier in the command. See the VAX/VMS DCL Concepts Manual 
for more information. Note that the /LISTING qualifier only controls 
whether or not VAX BASIC produces a listing file. The /SHOW qualifier 
controls which parts of the listing are produced. 


The /NOLISTING qualifier specifies that no source listing file be 
produced. 


At a terminal, the default is /NOLISTING. In batch mode, the default is 
/LISTING. 


/[NO]JMACHINE_CODE 

The /MACHINE_CODE qualifier specifies that the listing file includes 
the compiler-generated object code. If /LISTING is not specified, 
/MACHINE_CODE causes VAX BASIC to produce a listing file containing 
only the compiler-generated object code. 


The /NOMACHINE_CODE qualifier specifies that the listing file not 
include compiler-generated object code. 


The default is /NOMACHINE_CODE. 


/(NOJOBJECT 

The /OBJECT qualifier causes VAX BASIC to produce an object module, 

and optionally specifies its file name. By default, VAX BASIC generates 

object files as follows: 

¢ If you specify one source file, VAX BASIC generates one object file. 

e If you specify multiple source files separated by plus signs, VAX 
BASIC appends the files and generates one object file. 


e If you specify multiple source files separated by commas, VAX BASIC 
compiles and generates a separate object file for each source file. 
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e You can use both plus signs and commas in the same command line 
to produce different combinations of appended and separated object 
files. 


To produce an object file with an explicit file specification, you must use 
the /OBJECT qualifier in the form /OBJECT = file-spec. Otherwise, the 
object file has the same name as its corresponding source file and a file 
type of OBJ. All other file specification attributes depend on the placement 
of the qualifier in the command. See the VAX/VMS DCL Concepts Manual 
for more information. 


The /NOOBJECT qualifier suppresses the creation of an object file. During 
the early stages of program development, you may find it helpful to 
suppress the production of object files until your source program compiles 
without errors. 


The default is /OBJECT. 


/AINOJOLD_VERSION=CDD_ARRAYS 

The /OLD_VERSION=CDD_ARRAYS qualifier is provided for com- 
patibility with previous versions of BASIC. When you use the /OLD_ 
VERSION=CDD_ARRAYS qualifier, VAX BASIC changes the lower bound 
to zero and adjusts the upper bound of the array. For example, Array 

2:5 in the CDD is translated by VAX BASIC to be an array with a lower 
bound of 0 and an upper bound of 3. VAX BASIC issues an informational 
message to confirm the array bounds. 


The /NOOLD_VERSION=CDD_ARRAYS qualifier causes VAX BASIC 

to extract an array from the Common Data Dictionary (CDD) with the 
bounds as specified in the data definition. For example, Array 2:5 in the 
CDD is translated by VAX BASIC to be an array with a lower bound of 2 
and an upper bound of 5. The CDD assumes a default lower bound of 1, 
if none is specified. Therefore, if no lower bound is specified, VAX BASIC 
translates the CDD array to have a lower bound of 1. For example, 

Array 5 in the CDD is translated by VAX BASIC to be an array with a 
lower bound of 1 and an upper bound of 5. 


The default is /NOOLD_VERSION=CDD_ARRAYS. 


SINGLE 
- ) DOUBLE 
/REAL_SIZE GFLOAT 
HFLOAT 
The /REAL_SIZE qualifier lets you specify the default size for floating- 


point data. 
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The default is /REAL_—SIZE = SINGLE. The default floating-point size 
applies to all floating-point variables whose size is not explicitly declared. 


See the VAX BASIC Reference Manual for more information on floating- 
point data types. 


/[NOJROUND_DECIMAL 
The /ROUND qualifier specifies that VAX BASIC is to round packed 
decimal numbers rather than truncate them. 


The /NOROUND qualifier causes VAX BASIC to truncate packed decimal 
numbers rather than round them. 


The default is /NOROUND. 


/SCALE =n 

The /SCALE qualifier specifies a scale factor between zero and six, 
inclusive. The scale factor affects only double-precision numbers. SCALE 
helps to control accumulated round-off errors by multiplying floating-point 
values by 10 raised to the scale factor before storing them in variables. 
/SCALE is ignored for all but double-precision floating-point numbers. 


/SCALE is provided for compatibility with existing programs and with 
other implementations of VAX BASIC. DIGITAL recommends that you do 
not use this feature for new program development. Accumulated round- 
off errors can be better controlled with packed decimal numbers. See the 
VAX BASIC Reference Manual for more information on packed decimal 
numbers. 


The default is /SCALE = 0. 


[NO]JCDD_DEFINITIONS 

[NOJENVIRONMENT 

[NOJINCLUDE 
/(NOJSHOW = . [NOJMAP 

[NOJOVERRIDE 

ALL 

NONE 
The /SHOW qualifier determines which parts of the compilation listing 
are created. The /LISTING qualifier must be in effect for /SHOW to have 
any effect. The CDD_DEFINITIONS clause controls whether the trans- 
lation of a CDD record is displayed in the listing. The ENVIRONMENT 
clause lets you display all defaults that were in effect when the program 
was compiled. This is the compilation listing equivalent of the SHOW 
command in the environment. The INCLUDE clause controls whether 
files accessed with the %INCLUDE directive are displayed in the listing. 
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The MAP clause determines whether the listing contains an allocation 
map. The allocation map lists all program variables, their size and their 
data type. The OVERRIDE clause helps you debug code by disabling the 
effect of the %NOLIST directive. 


The /NOSHOW qualifier causes VAX BASIC to only display the source 
listing. 


/SHOW = ALL is the same as /SHOW = (CDD_DEFINITIONS, 
ENVIRONMENT, INCLUDE, MAP, OVERRIDE). /SHOW = NONE is 
the same as /NOSHOW. 


The default is /SHOW = (CDD_DEFINITIONS, ENVIRONMENT, 
INCLUDE, MAP, NOOVERRIDE). 


ANOJSYNTAX_CHECK 

The /SYNTAX_CHECK qualifier causes VAX BASIC to perform line- 
by-line syntax checking. When syntax checking is enabled, VAX BASIC 
immediately checks the syntax of every text line as soon as you type a 
carriage return. When syntax checking is disabled, VAX BASIC does not 
perform syntax checking until you COMPILE or RUN the program. 


The /NOSYNTAX—CHECK qualifier causes VAX BASIC to suppress 
line-by-line syntax checking. 


The default is /NOSYNTAX_CHECK. 


INTEGER 
-) REAL 
/TYPE_DEFAULT DECIMAL 


EXPLICIT 
The /TYPE_DEFAULT qualifier lets you specify the default data type for 
numeric variables. 


Specifying EXPLICIT means that all program variables must be explicitly 
declared in DECLARE, EXTERNAL, COMMON, MAP or DIM statements. 
Specifying INTEGER, REAL, or DECIMAL means only that variables 
and data which are not explicitly declared default to integer, real or 
packed decimal. To specify the actual size of variables and data, use the 
INTEGER_SIZE, REAL_SIZE and DECIMAL _SIZE qualifiers. 


The default is /TYPE_DEFAULT = REAL. 
/VARIANT = int-const 
The /VARIANT qualifier lets you specify the value associated with the 


lexical function % VARIANT. See Chapter 18 in this manual for more 
information about VARIANT and the %VARIANT lexical function. 
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If /VARIANT is not specified, the default value is 0. If /VARIANT is 
specified without a value, the default is 1. 


[NO]WARNINGS 
_ } [NOJINFORMATIONALS 
/INOJWARNINGS= } J ht 


NONE 
The /WARNINGS qualifier lets you specify whether VAX BASIC 
displays informational and warning error messages. Specifying 
/WARNINGS=NOWARNINGS causes VAX BASIC to display 
informational errors but not warning errors. Specifying 
/WARNINGS=NOINFORMATIONALS causes VAX BASIC to display 
warning errors but not informational errors. 


The /NOWARNINGS qualifier causes VAX BASIC to suppress any infor- 
mational or warning errors. 


/WARNINGS = ALL is the same as /WARNINGS = (INFORMATIONAL, 
WARNINGS). /WARNINGS = NONE is the same as /NOWARNINGS. 


The default is /WARNINGS = (INFORMATIONAL, WARNINGS). 


4.2.3 Compiler Listings 


A compiler listing provides information that can help you debug your VAX 
BASIC program. To generate a listing file, specify the /LISTING qualifier 
when you compile your VAX BASIC program interactively. For example: 


$ BASIC/LISTING prog-name 


If the program is compiled as a batch job, the listing file is created by 
default; specify the /NOLISTING qualifier to suppress creation of the 
listing file. By default, the name of the listing file is the name of the 
source program followed by a file type of LIS. You can include a file 
specification with the /LISTING qualifier to override this default. 


A compiler listing generated by the /LISTING qualifier has the following 
major sections: 


¢ Source Program Listing 


The source program section contains the source code and line numbers 
generated by the compiler. 
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e¢ Allocation Map 


The allocation map section contains summary information on program 
sections, variables, and arrays. 


¢ Qualifier Summary 


The qualifier summary section lists the qualifiers used with the BASIC 
command and the compilation statistics. 


Example 4-1 illustrates a compiler listing generated by the following 
command: 


$ BASIC/LIST/CROSS_REFERENCE/MACHINE_CODE lister 


Sections that follow the example describe each major section of the listing 
file. The numbered explanations in each section correspond to the callouts 
in the example. 
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Example 4-1: VAX BASIC Compiler Listing 
o 2] 3 4 
LISTER$MAIN Listing Tester sloaiyy 11:27:36 VAX a es Page 1 
Vi.5 ° Test 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER. BAS ; 2 
1 10 “TITLE "Listing Tester" 
2 “SBITL "Test" 
3 4IDENT "V1.5" 
4 
5 !'This program only shows the format of a listing 
6 !file. It does no useful work. 
7 
3 © %INCLUDE "MAPS .DEF" 
9 I1 ! MAPS definition file 
10 [1 MAP (SHARED) STRING A= 16, & 
11 I1 LONG B, & 
12 I1 DOUBLE C, & 
13° «1 BYTE D 
14 DECLARE INTEGER INDEX 
15 DECLARE LONG CONSTANT TRUE = -1 
16 DECLARE SINGLE Q(5) 
17 
18 “IF LVARIANT = 2 
i9 © “THEN 
20 Fi DECLARE DOUBLE 2Z(10) 
21 %END %IF 
22 
23 
24 First_loop: 
25 FOR INDEX = 0 TO 5 
26 PRINT Q(INDEX) 
27 NEXT INDEX 
28 
29 Second_loop: 
30 WHILE TRUE 
31 INDEX = INDEX + 1 
32 EXIT Second_loop IF INDEX => 5 
33 NEXT 
34 
35 32767 END 
36 


(Continued on next page) 
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Example 4-1 (Cont.): VAX BASIC Compiler Listing 


LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 2 
Cross Reference 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER.BAS;2 
®© 
User Identifier Cross Reference 
Symbol Datatype Name Type 
Hen nn en nee eee + 


# Defining reference 

@ Destructive reference 
P Parameter reference 
R Redefining reference 


a ae 
a a 


Hr rr te et rn tr rete ner cce + 

A STR=16 MAP SHARED + 0 
10 # 

B LONG MAP SHARED + 16 
11 # 

Cc DOUBLE MAP SHARED + 20 
12 # 

D BYTE MAP SHARED + 28 
13 # 

INDEX LONG 
14 # 25 26 27 31 @ 32 

QQ SINGLE 
16 # 26 

TRUE LONG CONSTANT 
15 # 30 


(Continued on next page) 
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Example 4-1 (Cont.): VAX BASIC Compiler Listing 


LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 3 

Cross one Map 19-MAY-1986 11:10:56 MY$$DISK: [SMITH]LISTER.BAS;2 

Map Cross Reference 

Symbol References 

SHARED MAP 
10 # 

A STR=16 MAP SHARED + 0 
10 # 

B LONG MAP SHARED + 16 
11 # 

Cc DOUBLE MAP SHARED + 20 
12 # 

D BYTE MAP SHARED + 28 
13 # 

@ 

Label Cross Reference 

Symbol References 

FIRST_LOOP 
24 # 

SECOND_LOOP 
29 # 32 

LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 4 


ALLOCATION MAP 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER. BAS; 2 


® 
Allocation information for MAP SHARED 
Name Offset Size Type 
A 0 16 Static string 
B 16 4 Long 
Cc 20 8 Double 
D 28 1 Byte 


(Continued on next page) 
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Example 4—1 (Cont.): VAX BASIC Compiler Listing 


© 
Named constants 
Name Type Value 
TRUE Long -1 
® 
Allocation information for main program LISTER Offset based on (Ri1) 
Name Offset Size Type 
INDEX 111 4 Long 
Q 87 24 Single 
Dimensions : ( 0 TO 5 ) 
© 
PROGRAM SECTIONS 
Name Bytes Attributes 
O $PDATA 112 PIC CON REL LCL SHR NOEXE RD NOWRT LONG 
1 $CODE 164 PIC CON REL LCL SHR EXE’ RD NOWRT LONG 
2 $ARRAY O PIC CON REL LCL NOSHR NOEXE RD WRT LONG 
3 $DESC O PIC CON REL LCL NOSHR NOEXE RD WRT LONG 
4 SHARED 29 PIC OVR REL GBL SHR NOEXE RD _ WRT LONG 
17) 
EXTERNAL REFERENCES 
OTS$LINKAGE BAS$LINKAGE BAS$INIT_R8 BAS$END_R8 


BAS$PRINT BAS$IO_END BAS$OUT_F_V_B 


(Continued on next page) 
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Example 4-1 (Cont.): VAX BASIC Compiler Listing 


cae? pas Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 65 


Qualifier summary 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER .BAS;2 


DEFAULT DATA TYPE INFORMATION: 
Data type : REAL 
Real size : SINGLE 
Integer size : LONG 
Decimal size : (15,2) 
Scale factor : 0 
NO Round decimal numbers 


COMPILATION QUALIFIERS IN EFFECT: 
Object file 
Overflow check integers 
Overflow check decimal numbers 
Bounds checking 
NO Syntax checking 


LISTING FILE INFORMATION INCLUDES: 
List 
Cross reference 
CDD Definitions 
Environment 
NO Override of %NOLIST 
Machine code 
Map 
INCLUDE files 


FLAGGERS : 
NO Declining features 
NO BASIC PLUS 2 subset 


Line 
Variant : 0 DEBUG INFORMATION: 
Warnings Traceback records 
Informationals NO Debug symbol records 
Setup 
Object Libraries : NONE 
macau Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 6 
Generated code 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER .BAS;2 
0000: -TITLE LISTER$MAIN 
0000: -IDENT V1.5 
0000: -PSECT $PDATA 
OOOOOOS5F 0000: -LONG 95 
O000005C 0004: -LONG 92 


10000103 0008: 


-LONG 469762307 


(Continued on next page) 
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Example 4-1 (Cont.): 


00000058 
00000000 
00000001 


O000006C 


0000006C 
00000060 
52 45 54 53 49 4C 06 


oc 


00000002 
OOOA 
0016 
7FFF 
008E 


CFFC 

52 FB AF 9E 

50 00000004 OG 9E 
51 50 DO 
00000000 GG 16 


FC AD FD AF 9E 


VAX BASIC Compiler Listing 


Oo00c: 
0010: 
0014: 
0018: 
ooic: 
0020: 
0024: 
0028: 
002C: 
0030: 
0034: 
0038 : 
003C: 
0040: 
0044: 
0048: 
Q04C: 
0050: 
0054: 
0058: 
OO5C: 
0063: 
0063: 
0064: 
0064: 
0064: 
0068 : 
006A: 
O06C: 
OO6E: 
0070: 
0000: 
0000: 
0000: 
0002: 
0006 : 
OOoOoD: 
0010: 
0016: 
0016: 


- LONG 
. LONG 
. LONG 
- LONG 
. LONG 
. LONG 
- LONG 
- LONG 
- LONG 
-LONG 
- LONG 
. LONG 
- LONG 
- LONG 
- LONG 
- LONG 
. LONG 
- LONG 
- LONG 
- LONG 
-ASCIC 


- PACKED 


- LONG 
. WORD 
- WORD 
- WORD 
. WORD 


-PSECT 


LISTER$MAIN: : 


$T_0016: 
$L_10: 


. WORD 
MOVAB 
MOVAB 
MOVL 
JSB 


MOVAB 
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PEO 20 Oro Se 


a 


ono Ooo°0o 
am 


95 

108 

(0) 

108 

96 

"LISTER" 

Decimal constants 
+0 

String constanta 
ERL table 

2 

10 

22 

32767 

142 


$CODE 
“M<R2,R3,R4,R5,R6,R7,R8,R9,R10,R11,1V,DV> 
.-3, R2 

$PDATA+4, RO 

RO, R1 

BAS$INIT_R8 


$L_10, -4(FP) ; 0025 


(Continued on next page) 


Example 4-1 (Cont.): VAX BASIC Compiler Listing 


001B: FIRST_LOOP: 


FC AD FD AF 9E 001B: MOVAB .-1i, -4(FP) 
6F AB 00 DO 0020: MOVL #0, INDEX(R11) 
FC AD FD AF 9E 0024: $T_0024:MOVAB  .-1, -4(FP) 
00 DD 0029: PUSHL #0 ; 0026 
00000000 GG 01 FB 002B: CALLS #1, BAS$PRINT 
5C 00 01 05 00 6F AB OA 0032: INDEX INDEX(R11), #0, #5, #1, #0, R12 
7E 57 AB 4C 50 OO3A: MOVF Q(R11) [R12], -(SP) 
00000000 GG 01 FB O03F: CALLS #1, BAS$OUT_F_V_B 
00000000 GG 00 FB 0046: CALLS #0, BAS$IO_END 
FC AD FD AF 9E O04D: $T_OO4D:MOVAB’ .-1, -4(FP) ; 0027 
LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 7 
Generated 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER .BAS;2 
CD 6F AB 05 F3 0052: AOBLEQ #5, INDEX(Ri1), $T_0024 
6F AB D7 0057: DECL INDEX (R11) 
FC AD FD AF 9E OOSA: $T_OOSA:MOVAB .-1, -4(FP) 
OO5F: SECOND_LOOP: ; 0030 
FC AD FD AF 9E_ OOS5F: MOVAB .-1, -4(FP) 
FC AD FD AF 9E 0064: $T_0064:MOVAB- .-1, -4(FP) 
FFFFFFFF 8F D5 0069: TSTL #-1 
18 13 OO6F: BEQL $T_0089 
5C 6F AB 4E 0071: CVTLF INDEX(R11), R12 ; 0031 
5C 08 40 0075: ADDF2 #8, R12 
6F AB 5C 4A 0078: CVIFL R12, INDEX(R11) 
5C 6F AB 4E OOT7C: CVILF INDEX(R11), R12 ; 0032 
1A 5C 51 0080: CMPF R12, #26 
02 19 0083: BLSS $T_0087 
02 11 0085: BRB $T_0089 
DB 11 0087: $T_0087:BRB $T_0064 ; 0033 
FC AD FD AF 9E 0089: $T_O0089:MOVAB .-1i, -4(FP) 
OO8E: 
OO8E: $L_32767: ; 0035 
FC AD FD AF 9E_ OOB8E: MOVAB $L_32767, -4(FP) 
50 00000004 0G 9E 0093: MOVAB $PDATA+4, RO 
00000000 GG 16 OO9A: JSB BAS$END_R8 
50 01 DO OOAO: MOVL #1, RO 
04 OOA3: RET 
OOA4: .END ; 0036 


4.2.3.1. Source Program Listing 


The source program section of the compiler listing contains the source 
code plus listing line numbers generated by the compiler. 
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Oo 2) 3) 4) 


LISTER$MAIN Listing Tester a ae 11:27:36 VAX BASIC 6 Page 1 
6 Test 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER.BAS; 2 

1 10 “TITLE "Listing Tester" 

2 “SBITL "Test" 

3 “IDENT "V1.5" 

4 

5 !This program only shows the format of a listing 
6 !file. It does no useful work. 

7 

8s © %INCLUDE "MAPS .DEF" 

9 I1 ! MAPS definition file 

10 I1 MAP (SHARED) STRING A= 16, & 
11 Ii LONG B, & 
12 11 DOUBLE C, & 
13 I1 BYTE D 

14 DECLARE INTEGER INDEX 

15 DECLARE LONG CONSTANT TRUE = -1 

16 DECLARE SINGLE Q(5) 

17 

18 “IF Y%VARIANT = 2 

19 © “THEN 
20 F1 DECLARE DOUBLE Z(10) 

21 %END 4IF 

22 

23 

24 First loop: 

25 FOR INDEX = 0 TO 5 

26 PRINT Q(INDEX) 

27 NEXT INDEX 

28 

29 Second_loop: 

30 WHILE TRUE 
31 INDEX = INDEX + 1 
32 EXIT Second_loop IF INDEX => 5 
33 NEXT 
34 

35 32767 END 
36 


@ The module name, which corresponds to the name in the program or 
module heading. 


The date (day, month, year) and time (hour, minute, second) of 
compilation. 


The VAX BASIC compiler name and version number. 
The page number. 


ooo Oo 


The date (day, month, year) and time (hour, minute, second) of source 
file creation. 
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The VAX/VMS file specification of the source file that is being com- 
piled. 


The source code listing line numbers. 


The compiler assigns unique line numbers to the lines of source 

code in a BASIC compilation unit. These line numbers appear in the 
leftmost column of the source code listing. The symbolic traceback 
that is printed if your program encounters an error at run time refers 
to these line numbers; in addition, the VAX/VMS Debugger uses these 
line numbers when controlling program execution. 


© The %INCLUDE file information. 


The “I” tells you that this code was extracted from a %INCLUDE 
file. The number following the “I” tells you the depth of nested 
%INCLUDE directives. Because this %INCLUDE directive occurs in 
the source program, the number is “1”. If the %INCLUDE file itself 
contained a %INCLUDE directive, the code extracted from that file 
would be numbered “2”, and so on. 


© A true-false flag for the %IF... THEN...ELSE...END...IF directives. 


Lines marked with “T” are compiled. Lines marked with “F” are not 
compiled. 


4.2.3.2 Cross-Reference Listing 


If you specified the /CROSS_REFERENCE qualifier, your listing includes 
a section displaying a list of the names of every identifier, both predeclared 
and user-declared, and every label to which the source code refers. 


LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 2 
Cross Reference 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER .BAS; 2 
© 
User Identifier Cross Reference 
Symbol Datatype Name Type 
Hao nn nn ee eee + 


# Defining reference ! 
@ Destructive reference ! 
P Parameter reference ! 
R Redefining reference ! 


A STR=16 MAP SHARED + 0 
10 # 


B LONG MAP SHARED + 16 
11 # 
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Cc DOUBLE MAP SHARED + 20 


12 # 
D BYTE MAP SHARED + 28 
13 # 
INDEX LONG 
14 # 25 26 27 31 @ 32 
QQ SINGLE 
16 # 26 
TRUE LONG CONSTANT 
15 # 30 
LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 3 
ahi, aaa Map 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER .BAS ;2 
Map Cross Reference 
Symbol References 
SHARED MAP 
10 # 
A STR=16 MAP SHARED + 0 
10 # 
B LONG MAP SHARED + 16 
11 # 
C DOUBLE MAP SHARED + 20 
12 # 
D BYTE MAP SHARED + 28 
13 # 
® 
Label Cross Reference 
Symbol References 
FIRST_LOOP 
24 # 


SECOND_LOOP 
29 # 32 


@ The cross-reference listing for variables and named constants. 


This tells you the variable names, the line number (if any) and 
statement at which they are referenced, their data type, the PSECT 
containing them (if any), and their offset from the start of the PSECT. 


@ The cross-reference listing for mapped variables. 


This tells you the variable names, the line number and statement 
number at which they are referenced, their data type, and their offset 
from the start of the MAP PSECT. 
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@® The label cross-reference listing for labels. 


This tells you the label names and the line number and statement at 
which they are referenced. 


4.2.3.3 Allocation Map 
The allocation map portion of a compiler listing contains summary in- 
formation on program sections, variables, and arrays. If you specified 
the /CROSS_REFERENCE in addition to the /LISTING qualifier, the 
allocation map also contains the following cross reference information: 
¢ Listing lines where symbols are defined and initialized 
e Listing lines where the values of symbols are modified 
e Listing lines where symbols are actual arguments 
e¢ Number of times a symbol occurs in each line 


LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 4 
ALLOCATION MAP 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER. BAS; 2 


® 
Allocation information for MAP SHARED 
Name Offset Size Type 
A 0 16 Static string 
B 16 4 Long 
Cc 20 8 Double 
D 28 1 Byte 
© 
Named constants 
Name Type Value 
TRUE Long -1 
® 
Allocation information for main program LISTER Offset based on (R11) 
Name Offset Size Type 
INDEX 111 4 Long 
Q 87 24 Single 
Dimensions : ( 0 TO 5 ) 
© 


PROGRAM SECTIONS 
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Name 
O $PDATA 
1 $CODE 
2 SARRAY 
3 $DESC 
4 SHARED 
® 
EXTERNAL REFERENCES 
OTS$LINKAGE 
BAS$PRINT 
® 
® 
® 
© 
® 


Bytes Attributes 


112 PIC CON REL LCL SHR NOEXE’ RD NOWRT LONG 
164 PIC CON REL LCL SHR’ EXE’ RD NOWRT LONG 
OQ PIC CON REL LCL NOSHR NOEXE RD _ WRT LONG 
O PIC CON REL LCL NOSHR NOEXE RD WRT LONG 
29 PIC OVR REL GBL SHR NOEXE RD _ WRT LONG 


BAS$LINKAGE BAS$INIT_R8 BAS$END_R8 
BAS$IO_END BAS$OUT_F_V_B 


The allocation listing for the MAP named SHARED. 


This tells you the names of all variables in the MAP, their offset, in 
bytes, from the beginning of the MAP, their size in bytes, and their 
data type. 


A list of named constants. 


This tells you the names of all explicitly declared constants, their data 
type, and the value assigned to them. 


The allocation listing for dynamic variables. 


This part of the listing applies to variables that are neither parameters 
nor part of a COMMON or MAP PSECT. This tells you the names of 
the variables, their offset from R11, their size in bytes and their data 
type. 

A list of the program sections (PSECTs). 


This tells you the names of the PSECTs, their size in bytes and 
their attributes. See the VAX/VMS Linker Reference Manual for more 
information on PSECT attributes. 


A list of all external references. 


This includes subprograms, external variables, constants, functions, 
and routines, and the RTL routines invoked to support VAX BASIC 
language elements. See the VAX/VMS Run-Time Library Routines 
Reference Manual for more information on these RTL routines. 
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4.2.3.4 Qualifier Summary 


The compilation summary lists the qualifiers used with the BASIC com- 
mand and the compilation statistics. 


a ea Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 5 


Qualifier summary 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER. BAS ;2 


DEFAULT DATA TYPE INFORMATION: 
Data type : REAL 
Real size : SINGLE 
Integer size : LONG 
Decimal size : (15,2) 
Scale factor : 0 
NO Round decimal numbers 


COMPILATION QUALIFIERS IN EFFECT: 

Object file 
Overflow check integers 
Overflow check decimal numbers 
Bounds checking 

NO Syntax checking 
Line 
Variant : 0 
Warnings 
Infornationals 
Setup 
Object Libraries : NONE 


LISTING FILE INFORMATION INCLUDES: 
List 
Cross reference 
CDD Definitions 
Environment 
NO Override of %NOLIST 
Machine code 
Map 
INCLUDE files 


FLAGGERS : 
NO Declining features 
NO BASIC PLUS 2 subset 


DEBUG INFORMATION: 
Traceback records 
NO Debug symbol records 


® A list of the compiler defaults in effect when the program was 


compiled. 


4.2.3.5 Machine Code Listing 


If you specified the /MACHINE qualifier, your listing includes a section 
displaying compiler-generated object code. 


oe Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 6 
Generated code 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER .BAS; 2 
0000: .TITLE LISTER$MAIN 
0000: -IDENT V1.5 
0000: -PSECT $PDATA 
OOOOOO5F 0000: -LONG 95 
OOOOOO0SC 0004: . LONG 92 
10000103 0008: . LONG 469762307 
00000058 000C: . LONG 88 
00000000 0010: . LONG (¢] 
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52 45 54 53 


52 


00000001 
00000000 
00000000 
00000000 
00000000 
00000000 
00000000 
00000018 
00000000 
00000000 
QOOOOO5F 
OOOOOO5F 
00000000 
QOOO005F 
0000006C 
00000000 
0000006C 
00000060 


49 4C 06 


oc 


00000002 
OOOA 
0016 
TFFF 
008E 


FB AF 9E 


50 00000004 OG 9E 


51 50 DO 


00000000 GG 16 


FC AD 


FC AD 
6F 
FC AD 


00000000 

5C 00 01 05 00 
TE 57 

00000000 
00000000 

FC AD 


FD AF 9E 


FD AF 9E 
AB 00 DO 
FD AF QE 


GG 01 FB 
6F AB OA 


GG 01 FB 
GG 00 FB 
FD AF 9E 


0014: 
0018: 
ooic: 
0020: 
0024: 
0028: 
002C: 
0030: 
0034: 
0038 : 
003C: 
0040: 
0044: 
0048: 
004C: 
0050: 
0054: 
0058: 


OosC: 
0063: 
0063: 
0064: 
0064: 
0064: 
0068: 
OO6A: 
oo6C: 
OO6E: 
0070: 
0000: 
0000: 
0000: 
0002: 
0006: 
OOOD: 
0010: 
0016: 
0016: 
001B: 
001B: 
0020: 
0024: 
0029: 


002B: 
0032: 
OO3A: 
OO3F: 
0046: 
004D: 


. LONG 
. LONG 
- LONG 
- LONG 
. LONG 
- LONG 
- LONG 
- LONG 
. LONG 
. LONG 
. LONG 
. LONG 
. LONG 
. LONG 
. LONG 
. LONG 
. LONG 
. LONG 


. ASCIC 


- PACKED 


- LONG 
. WORD 
- WORD 
- WORD 
- WORD 


.PSECT 
LISTER$MAIN: : 
- WORD 
MOVAB 
MOVAB 
MOVL 
JSB 
$T_0016: 
$L_10: MOVAB 
FIRST_LOOP: 
MOVAB 
MOVL 
$T_0024 : MOVAB 
PUSHL 


CALLS 
INDEX 
MOVF 
CALLS 
CALLS 
$T_004D : MOVAB 
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» ooor 


OCONOC OO 


ooo 
an 


95 
108 
0 
108 
96 


"LISTER" 

Decimal constants 
+0 

String constants 
ERL table 

2 

10 

22 

32767 

142 


$CODE 


“M<R2,R3,R4,R5,R6,R7,R8,RO,R10, R11, IV, DV> 
.73, R2 

SPDATA+4, RO 

RO, Ri 

BASSINIT_R8 


$L_10, -4(FP) ; 0025 
.71, -4(FP) 

#0, INDEX(R11) 

S21; -4(FP) 

#0 ; 0026 


#1, BAS$PRINT 

INDEX(R11), #0, #5, #1, #0, R12 
Q(R11) [R12], -(SP) 

#1, BAS$OUT_F_V_B 


#0, BAS$IO_END 
.71, -4(FP) ; 0027 


LISTER$MAIN Listing Tester 19-MAY-1986 11:27:36 VAX BASIC V3.0 Page 7 


Generated 19-MAY-1986 11:10:56 MY$$DISK: [SMITH] LISTER. BAS; 2 
CD 6F AB OS F3 0052: AOBLEQ #5, INDEX(R11), $T_0024 
6F AB D7 0057: DECL INDEX (Ri1) 
FC AD FD AF 9E OO5A: $T_OO5A:MOVAB .c1, -4(FP) 
OO5F: SECOND_LOOP: ; 0030 
FC AD FD AF 9E OOSF: MOVAB .-1, -4(FP) 
FC AD FD AF 9E 0064: $T_0064:MOVAB- .-1, -4(FP) 
FFFFFFFF 8F D5 0069: TSTL = #-1 
18 13 OO6F: BEQL  $T_0089 
5C 6F AB 4E 0071: CVILF INDEX(R11), R12 ; 0031 
5C 08 40 0075: ADDF2 #8, R12 
6F AB 5C 4A 0078: CVTFL R12, INDEX(R1i1) 
5C 6F AB 4E OO7C: CVTLF INDEX(R11), R12 ; 0032 
1A 5C 51 0080: CMPF Ri2, #26 
02 19 0083: BLSS $T_0087 
02 11 0085: BRB $T_0089 
DB 11 0087: $T_0087:BRB $T_0064 ; 0033 
FC AD FD AF 9E 0089: $T_0089:MOVAB .c1, -4(FP) 
OO8E: 
OO8E: $L_32767: ; 0035 
FC AD FD AF 9E OO8E: MOVAB $L_32767, -4(FP) 
50 00000004 0G 9E 0093: MOVAB $PDATA+4, RO 
00000000 GG 16 OO9A: JSB BAS$END_R8 
50 01 DO OOAO: MOVL #1, RO 
04 OOA3: RET 
OOA4: . END ; 0036 


® A list of the compiler-generated machine code. 


For a thorough understanding of this code, you should be an ex- 
perienced VAX MACRO programmer. The naming scheme for the 
compiler-generated labels is explained as follows: 


— Symbols beginning with $L—n are line-number labels, where n is 
the line number. 


— Symbols beginning with $T_n are compiler-generated labels, 
where 7 is the relative PC of the location. 


Note that these labels are used to improve the readability of the listing 
and are not accessible from the VAX/VMS Debugger. See the VAX/VMS 


Run-Time Library Routines Reference Manual for more information on BAS$ 
and OTS$ routines. 
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4.3 Linking a VAX BASIC Program 


On VAX/VMS systems, the linker simplifies the job of each language 
compiler because the logic needed to resolve symbolic references need 
not be duplicated. The main advantage to a system that has a linker, 
however, is that individual program modules can be separately written 
and compiled, and then linked together. This includes object modules 
produced by different language compilers. 


The VAX/VMS Linker performs the following functions: 


¢ Resolves local and global symbolic references in the object code 
e Assigns values to the global symbolic references 

e Signals an error message for any unresolved symbolic reference 
¢ Produces an executable image 


When using the LINK command on development systems, you may want 
to use the /DEBUG qualifier when you link your program module. The 
/DEBUG qualifier appends to the image all the symbol and line number 
information appended to the object modules plus information on global 
symbols, and forces the image to run under debugger control when it is 
executed. 


The LINK command produces an executable image by default. However, 
you can also use the LINK command to obtain shareable images and 
system images. The /SHAREABLE qualifier directs the linker to produce a 
shareable image; the /SYSTEM qualifier a system image. See Section 4.3.2 
for a complete description of these and other LINK command qualifiers. 


For a complete discussion of the VAX/VMS Linker, refer to the VAX/VMS 
Linker Reference Manual. 


4.3.1 The LINK Command 


Once you have compiled your source program or module, you link it 

by using the DCL command LINK. The LINK command combines your 
object modules into one executable image, which can then be executed by 
the VAX/VMS system. A source program or module cannot run on the 
VAX/VMS system until it is linked. The format of the LINK command is 
as follows: 


LINK (/command-qualifier]... {file-spec[/file-qualifier...]},... 
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/command-quailifier 
Specifies one or more output file options. 


file-spec 
Specifies the input file or files to be linked. 


/file-qualifier 
Specifies one or more input file options. 


If you specify more than one input file, you must separate the input file 
specifications with plus signs (+) or commas (,). By default, the linker 
creates an output file with the name of the first input file specified and the 
file type EXE. When you link more than one file, it is good practice to list 
the file containing the main program first. In this way, the name of your 
output file will have the same name as that of your main program module. 


The following command line links the object files DANCE.OBJ, 
CHACHA.OBJ, and SWING.OBJ to produce one executable image called 
DANCE.EXE: 


$ LINK DANCE.OBJ, CHACHA.OBJ, SWING.OBJ 


4.3.2 LINK Command Qualifiers 


The LINK command qualifiers can be used to modify the linker’s output, 
as well as to invoke the debugging and traceback facilities. Linker output 
consists of an image file and an optional map file. Image file qualifiers, 
map file qualifiers, and debugging and traceback qualifiers are described in 
this section. 


The following list summarizes some of the most commonly used LINK 
command qualifiers. A brief description of each qualifier follows this list. 
For a complete list and description of LINK qualifiers, see the VAX/VMS 
Linker Reference Manual. 


Command Qualifier Default 

/BRIEF /Default map 
/[NO]CROSS_REFERENCE /NOCROSS_REFERENCE 
/[NO]DEBUG [= file-spec] /NODEBUG 


[NOJEXECUT ABLE [= file-spec] /EXECUTABLE 
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/FULL /Default map 


/[NO]MAP [= file-spec] /NOMAP 
/[NOJSHAREABLE [= file-spec] //NOSHAREABLE 
/[NO}TRACEBACK /TRACEBACK 
/BRIEF 


The /BRIEF qualifier causes the linker to produce a summary of the 
image’s characteristics and a list of contributing modules. 


/[NOJCROSS_REFERENCE 
The /CROSS_REFERENCE qualifier causes the linker to produce cross- 
reference information for global symbols; the /NOCROSS_REFERENCE 


qualifier causes the linker to suppress cross-reference information. The 
default is /NOCROSS_REFERENCE. 


/{NO]DEBUG 

The /DEBUG qualifier causes the linker to include the VAX/VMS 
Debugger in the executable image and generates a symbol table; the 
/NODEBUG qualifier causes the linker to prevent debugger control of the 
program. The default is /NODEBUG. 


/AINOJEXECUTABLE 

The /EXECUTABLE qualifier causes the linker to produce an executable 
image; the /NOEXECUTABLE qualifier suppresses production of an image 
file. The default is /EXECUTABLE. 


/FULL 

The /FULL qualifier causes the linker to produce a summary of the 
image’s characteristics, a list of contributing modules, listings of global 
symbols by name and by value, and a summary of characteristics of image 
sections in the linked image. 


/(NOJMAP 

The /MAP qualifier causes the linker to generate a map file; the /NOMAP 
qualifier suppresses the map. The default is /MAP in batch mode and 
/NOMAP in interactive mode. 


/[NOJSHAREABLE 

The /SHAREABLE qualifier causes the linker to create a shareable image; 
the /NOSHAREABLE qualifier generates an executable image. The default 
is /NOSHAREABLE. 
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/A(NO]JTRACEBACK 

The /TRACEBACK qualifier causes the linker to generate symbolic 
traceback information when error messages are produced; the 
/NOTRACEBACK qualifier suppresses traceback information. The default 
is /TRACEBACK. 


4.3.3 Linker Input Files 


You can specify the object modules to be included in an executable image 
in any of the following ways: 


¢ Specify input file specifications for the object modules. 
If no file type is specified, the linker assumes that an input file is an 
object file with the file type OBJ. 

e Specify one or more object module library files. 
You can either specify the name of an object module library with the 
/LIBRARY qualifier, or specify the names of object modules contained 


in an object module library with the /INCLUDE qualifier. The uses of 
object module libraries are described in Section 4.3.5. 


¢ Specify an options file. 
An options file can contain additional file specifications for the 
LINK command as well as special linker options. You must use the 


/OPTIONS qualifier to specify an options file. For more information 
on options files see the VAX/VMS Linker Reference Manual. 


The linker uses the following default file types for input files. 


File File Type 
Object module OBJ 
Library OLB 
Options file OPT 


4.3.4 Linker Output Files 


When you enter the LINK command interactively and do not specify any 
qualifiers, the linker creates only an executable image file. By default, 
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the resulting image file has the same file name as the first object module 
specified, and a file type of EXE. 


In a batch job, the linker creates both an executable image file and a 
storage map file by default. The default file type for map files is MAP. 


To specify an alternative name for a map file or image file, or to specify an 
alternative output directory or device, you can include a file specification 
on the /MAP or /EXECUTABLE qualifier. For example: 


$ LINK UPDATE/MAP=TEST 


4.3.5 Using an Object Module Library 


In a large development effort, the object modules for subprograms are 
often stored in an object module library. By using an object module 
library, you can make program modules contained in the library available 
to many other programmers. To link modules contained in a object 
module library, use the /INCLUDE qualifier and specify the specific 
modules you want to link. For example: 


$ LINK GARDEN, VEGGIES/INCLUDE=(EGGPLANT , TOMATO, BROCCOLI , ONION) 


This example directs the linker to link the subprogram modules 
EGGPLANT, TOMATO, BROCCOLI, and ONION with the main program 
module GARDEN. 


Besides program modules, an object module library can also contain a 
symbol table with the names of each global symbol in the library, and 
the name of the module in which they are defined. You specify the 
name of the object module library containing symbol definitions with 
the /LIBRARY qualifier. When you use the /LIBRARY qualifier during a 
link operation, the linker searches the specified library for all unresolved 
references found in the included modules during compilation. 


In the following example, the linker uses the library RACQUETS to resolve 
undefined symbols in BADMINTON, TENNIS, and RACQUETBALL. 


$ LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY 


You can define an object module library, such as LNK$LIBRARY, to be 
your default library by using the DCL command DEFINE. The linker 
searches default user libraries for unresolved references after it searches 
modules and libraries specified in the LINK command. See the VAX/VMS 
DCL Dictionary for more information about the DEFINE command. 
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For more information about object module libraries, see the VAX/VMS 
Linker Reference Manual. 


4.3.6 Linker Error Messages 


If the linker detects any errors while linking object modules, it displays 
messages indicating the cause and severity of the error. If any error or 
fatal error conditions occur, (errors with severities of E or F) the linker 
does not produce an image file. 


The messages produced by the linker are descriptive, and you do not 
usually need additional information to determine the specific error. Some 
common errors that occur during linking are as follows: 


e An object module has compilation errors. 


This error occurs when you attempt to link a module that has warn- 
ings or errors during compilation. You can usually link compiled 
modules for which the compiler generated messages, but you should 
verify that the modules will actually produce the output you expect. 


e The input file has a file type other than OBJ and no file type was 
specified on the command line. 


If you do not specify a file type, the linker assumes the file has a file 
type of OBJ by default. If the file is not an object file and you do not 
identify it with the appropriate file type, the linker signals an error 
message and does not produce an image file. 


e You tried to link a nonexistent module. 
The linker signals an error message if you misspell a module name on 
the command line or if the compilation contains fatal diagnostics. 

e A reference to a symbol name remains unresolved. 
An error occurs when you omit required module or library names 
from the command line and the linker cannot locate the definition 
for a specified global symbol reference. For example, a main program 
module OCEAN.OBJ calls the subprograms REEF.OBJ, SHELLS.OBJ, 


and SEAWEED.OBJ. However, the rotlowing LINK command does not 
reference SEAWEED.OBJ: 


$ LINK OCEAN, REEF, SHELLS 
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This example produces the following error messages: 


“%LINK-W-NUDFSYMS, 1 undefined symbol 

YLINK-I-UDFSYMS , SEAWEED 

“4LINK-W-USEUNDEF, module "OCEAN" references undefined symbol "SEAWEED" 
“4LINK-W-DIAGISUED, completed but with diagnostics 


If an error occurs when you link modules, you can often correct the error 
by reentering the command string and specifying the correct modules or 
libraries. 


See the VAX/VMS System Messages and Recovery Procedures Reference 
Manual for a complete list of linker messages. 


4.4 Running a VAX BASIC Program 


Once you have linked your program, you use the DCL command RUN to 
execute it. The RUN command has the following format: 


RUN [/[NO]DEBUG] file-spec [/[NO) DEBUG] 


/{[NOJDEBUG 

The /[NOJDEBUG qualifier is optional. Specify the /DEBUG qualifier to 
request the debugger if the image was not linked with it. You cannot use 
/DEBUG on images linked with the /NOTRACEBACK qualifier. If the 
image was linked with the /DEBUG qualifier and you do not want the 
debugger to prompt, use the /NODEBUG qualifier. The default action 
depends on whether the file was linked with the /DEBUG qualifier. 


file-spec 
The name of the file you want to run. 


The following example executes the image SAMPLE.EXE without invoking 
the debugger: 


$ RUN SAMPLE/NODEBUG 
See Chapter 5 for more information on debugging programs. 


During program execution, an image can generate a fatal error called an 
exception condition. When an exception condition occurs, VAX BASIC 
displays an error message. Run-time errors can also be issued by other 
facilities such as, the VAX/VMS operating system. For more information 
on run-time errors, see Appendix B. 
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Chapter 5 


Using the VAX/VMS Debugger 


This chapter is an introduction to using the VAX/VMS Debugger with 
VAX BASIC programs. Included in the chapter are the following: 


e An overview of the debugger 
e Enough information to get you started using the debugger 


e Asample terminal session that demonstrates using the debugger to 
find a bug in a VAX BASIC program 


e A list of the debugger commands by function 


For complete reference information on the VAX/VMS Debugger, see the 
VAX/VMS Debugger Reference Manual. Online HELP is available during 
debugging sessions. 


5.1 Overview of the Debugger 


A debugger is a tool to help you locate run-time errors quickly. It is used 
with a program that has already been compiled and linked successfully, 
with no errors reported, but that does not run correctly. For example, 

the output may be obviously wrong, or the program goes into an infinite 
loop or terminates prematurely. The debugger enables you to observe and 
manipulate the program’s execution interactively, step by step, until you 
locate the point at which the program stopped working correctly. 


The VAX/VMS Debugger is a symbolic debugger, which means that you 

can refer to program locations by the symbols (names) you used for those 
locations in your program—the names of variables, routines, labels, and so 
on. You do not have to use virtual addresses to refer to memory locations. 
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The debugger recognizes the syntax, expressions, data typing, and other 
constructs of VAX BASIC, as well as the following other VAX/VMS- 
supported languages: 


Ada® 
BLISS 

Cc 

COBOL 
DIBOL 
FORTRAN 
MACRO-32 
PASCAL 
PL/I 

RPG II 
SCAN 


Therefore, if your program is written in more than one language, you 
can change from one language to another in the course of a debugging 
session. The current source language determines the format used for 
entering and displaying data, as well as other features that have language- 
specific settings (for example, comment characters, operators and operator 
precedence, and case sensitivity or insensitivity). 


By issuing debugger commands at your terminal, you can 


e Start, stop, and resume the program’s execution 

e Trace the execution path of the program 

¢ Monitor selected locations, variables, or events 

e Examine and modify the contents of variables, or force events to occur 


e Test the effect of some program modifications without having to edit, 
recompile, and relink the program 


Such techniques can enable you to isolate an error in your code much 
more quickly than you could without the debugger. 


Once you have found the error in the program, you can then edit the 
source code and compile, link, and run the corrected version. 


® Ada isa registered trademark of the U.S. Government (Ada Joint Program Office). 
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5.2 Features of the Debugger 


The VAX/VMS Debugger provides various features that help you to debug 
your programs: 


Online HELP. Online HELP is always available during a debugging 
session; it contains information on all of the debugger commands and 
selected topics. 


Source code display. The debugger lets you display lines of source 
code during a debugging session. 


Screen mode. In screen mode, you can display and capture various 
kinds of information in scrollable windows that can be moved around 
the screen and resized. Source, instruction, and register displays are 
automatically updated. You can selectively direct debugger input, 
output, and diagnostic messages to displays. (Screen mode is best dis- 
played on VT100-series or VT200-series terminals or MicroVAX/VMS 
workstations.) 


Keypad mode. When you invoke the debugger, several commonly 
used debugger command sequences are assigned by default to the 
keys of the numeric keypad (if you have a VT100, VT52, or LK201 
keypad). Using the keypad can be more efficient than typing com- 
mands because the keypad keys can save keystrokes. (See Figure 5-1 
for a diagram of the keypad key functions.) 


Source editing. As you find errors during a debugging session, you 
can use the EDIT command to invoke any editor available on your 
system. You specify the editor you want with the SET EDITOR 
command. 


Command procedures. You can direct the debugger to execute a 
command procedure (a file of debugger commands) to recreate a 
debugging session, to continue a previous session, or to avoid typing 
the same debugger commands many times during a debugging session. 


Symbol definitions. You can define your own symbols to represent 
lengthy commands, address expressions, or values in abbreviated 
form. 


Initialization files. You can create an initialization file containing 
commands to set your default debugging modes, screen display 
definitions, keypad key definitions, symbol definitions, and so on. 
In addition, you may want to have special initialization files for 
debugging specific programs. When you invoke the debugger, those 
commands will be executed automatically. 
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¢ Log files. You can record the commands you enter during a debugging 
session and the debugger’s responses to those commands in a log 
file. You can use log files to keep track of your debugging efforts, or 
you can use them as command procedures in subsequent debugging 
sessions. 


5.3 Getting Started with the Debugger 


This section explains how to use the debugger and provides VAX BASIC 
examples. The intent is to get you started using the debugger; therefore, 
only basic functions are covered. For more detailed information, see the 
VAX/VMS Debugger Reference Manual. Remember that online HELP is 
immediately available to you during a debugging session when you type 
the HELP command at the DBG> prompt. 


5.3.1. Compiling and Linking to Prepare for Debugging 


The following example shows how to compile and link a VAX BASIC 
program (consisting of a single compilation unit named INVENTORY) so 
that subsequently you will be able to use the debugger. 


$ BASIC/DEBUG INVENTORY 
$ LINK/DEBUG INVENTORY 


The /DEBUG qualifier on the BASIC command causes the compiler 

to write the debug symbol records associated with INVENTORY into 
the object module, INVENTORY.OBJ. These records allow you to use 
the names of variables and other symbols declared in INVENTORY in 
debugger commands. (If your program has several compilation units, 
you must compile each unit that you want to debug with the /DEBUG 
qualifier). 


The /DEBUG qualifier on the LINK command causes the linker to include 
all symbol information that is contained in INVENTORY.OBJ in the 
executable image. The qualifier also causes the VAX/VMS image activator 
to start the debugger at run time. (If your program has several object 
modules, you may need to specify other modules in the LINK command). 
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5.3.2 Starting and Terminating a Debugging Session 


To invoke the debugger, issue the DCL command RUN. The following 
message will appear on your screen. 


$ RUN INVENTORY 
VAX DEBUG Version 4.n 


“%DEBUG-I-INITIAL, language is BASIC, module set to 'INVENTORY$MAIN' 
DBG> 


The DBG> prompt indicates that you can now type debugger commands. 
At this point, if you type the GO command, program execution begins and 
continues until it is forced to pause or stop (for example, if the program 
prompts you for input, or an error occurs). 


The debugger suspends execution before the start of the main program, so 
that you can execute initialization code under debugger control. Typing 
the GO command will put you at the start of the main program. At that 
point, typing the GO command again will start program execution and 
continue it until it is forced to stop (for example, if the program prompts 
you for input, or an error occurs). 


To interrupt a debugging session while a debugging command is in 
progress, press CTRL/Y to return to DCL level. For example, if your 
program loops or otherwise fails to complete execution, press CTRL/Y to 
stop the debugging session and return to DCL level. 


After you have used CTRL/Y to interrupt a debugging session, you can 
resume the session by using the CONTINUE or DEBUG command at 
DCL level. In general, you use the CONTINUE command at DCL level to 
return to where you interrupted the debugging session. If you interrupted 
the session with CTRL/Y because of an infinite loop, you use the DCL 
command DEBUG instead of the CONTINUE command. The DEBUG 
command returns you to the debugger prompt so that you can type 
another command. For example: 


DBG> GO 


(infinite loop) 


Interrupt 


$ DEBUG 
DBG> 
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§.3.3 


The following message indicates that your program has completed 
successfully: 


%DEBUG-I-EXITSTATUS, is '(SYSTEM-S-NORMAL, normal successful completion' 
DBG> 


To end a debugging session, type the EXIT command at the DBG> 
prompt or press CTRL/Z: 


DBG> EXIT 
$ 


Issuing Debugger Commands 


You can issue debugger commands any time you see the debugger prompt 
(DBG> ). To enter a command, type it at the keyboard and press the 
RETURN key. You can issue several commands on a line by separating 
the command strings with semicolons (;). As with DCL commands, you 
can continue a command string on a new line by ending the line with a 
hyphen (-). 


Alternatively, you can use the numeric keypad. In addition to the STEP, 
GO, SHOW CALLS, and EXAMINE commands, several functions that ma- 
nipulate screen-mode displays are bound to the keys. Figure 5-1 identifies 
the predefined key functions. You can also redefine key functions with the 
DEFINE/KEY command. 


Most keypad keys have three predefined functions—-DEFAULT, GOLD, 
and BLUE. (The PF1 key is commonly known as the GOLD key, and 

the PF4 key is commonly known as the BLUE key.) To obtain a key’s 
DEFAULT function, press the key. To obtain its GOLD function, first 
press the PF1 (GOLD) key, and then the key. To obtain its BLUE function, 
first press the PF4 (BLUE) key, and then the key. 


In Figure 5-1, the DEFAULT, GOLD, and BLUE functions are listed 
within each key’s outline, from top to bottom respectively. For example, 
pressing keypad key 0 issues the STEP command (DEFAULT function); 
pressing key PF1 and then key 0 issues the STEP/INTO command (GOLD 
function); pressing key PF4 and then key 0 issues the STEP/OVER 
command (BLUE function). 


Type the HELP KEYPAD command to get help on the keypad key 
definitions. 
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Figure 5-1: 
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5.3.4 Viewing Your Source Code 


The debugger provides two methods for viewing source code: noscreen 
mode and screen mode. By default, when you invoke the debugger, you 
are in noscreen mode, but you may find that it is easier to view your 
source code with screen mode. Both modes are briefly described in the 
following sections. 


5.3.4.1 Noscreen Mode 


Noscreen mode is the default, line-oriented mode of displaying input 
and output. To get into noscreen mode from screen mode, type SET 
MODE NOSCREEN. See the sample debugging session in Section 5.4 for 
a demonstration of noscreen mode. 


In noscreen mode, you can use the TYPE command to display one or 
more source lines. For example, the following command displays line 3 of 
the module that is currently executing: 


DBG> TYPE 3 
3: EXTERNAL SUB TRIPLE & 
DBG> 


The display of source lines is independent of program execution. You can 
use the TYPE command to display source code from a module other than 
the one currently executing. In that case, you need to use a path name to 
specify the module. For example, the following command displays lines 
16 through 21 of module TEST: 


DBG> TYPE TEST\16:21 


5.3.4.2 Screen Mode 


To invoke screen mode, press keypad key PF3. In screen mode, by default 
the debugger splits the screen into three displays named SRC, OUT, and 
PROMPT. 
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--SRC: module SAMPLE$MAIN -scroll-source-------------------------- 


1: 10 !SAMPLE 
2: 
3: EXTERNAL SUB TRIPLE & 
4: ,» PRINT_SUB 
5: 
6: WHEN ERROR USE HANDLER_1 
-> 7: CALL TRIPLE 

8: CALL PRINT_SUB 
9: 

- QUT -output------ nnn nnn nner nen ne nn ren nner nnn nner cccce 


stepped to SAMPLE$MAIN\%LINE 7 


~ PROMPT -error-program-prompt------------ cern rere r ern nnn 
DBG> STEP 
DBG> 


The SRC display, at the top of the screen, shows the source code of the 
module (compilation unit) that is currently executing. An arrow in the left 
column points to the next line to be executed, which corresponds to the 
current location of the program counter (PC). The line numbers, which are 
assigned by the compiler, match those in a listing file. 


NOTE 


Note that VAX BASIC line numbers are treated as text by the 
debugger. In this chapter, line numbers refer to the sequential 
line numbers generated by the compiler. When a program 
includes or appends code from another file, the included lines 
of code are also numbered in sequence by the compiler. These 
line numbers are on the extreme left of a listing file. An 
explanation of the listing file format can be found in Chapter 4. 


The PROMPT display, at the bottom of the screen, shows the debugger 
prompt (DBG> ), your input, debugger diagnostic messages, and program 
output. In the illustration, it shows the two debugger commands that have 
been issued. 


The OUT display, in the center of the screen, captures the debugger’s 
output in response to the commands that you issue. 


The SRC and OUT displays are scrollable so that you can see whatever 
information may scroll beyond the display window’s edge. Use keypad 
key 8 to scroll up and keypad key 2 to scroll down. Use keypad key 3 to 
change the display to be scrolled (by default, the SRC display is scrolled). 
Scrolling a display does not affect program execution. 
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If the debugger cannot locate source lines for the currently executing 
module, it tries to display source lines in the next module down on the 
call stack for which source lines are available and issues the following 
message: 


%DEBUG-I-SOURCESCOPE, Source lines not available for .O\%PC. 


Displaying source in a caller of the current routine. 


Source lines may not be available for the following reasons: 


The PC is within a system routine, or a shareable image routine for 
which no source code is available. 

The PC is within a routine that was compiled without the /DEBUG 
compiler command qualifier (or with /NODEBUG). 


The source file was moved to a different directory after it was com- 
piled (the location of source files is embedded in the object modules). 


5.3.5 Controlling and Monitoring Program Execution 


This section covers the following topics: 


Starting and resuming program execution with the GO command 
Stepping through the program’s code with the STEP command 


Determining the current location of the program counter (PC) with the 
SHOW CALLS command 


Suspending program execution with breakpoints 
Tracing program execution with tracepoints 
Monitoring changes in variables with watchpoints 


5.3.5.1 Starting and Resuming Program Execution 


There are two commands for starting or resuming program execution: GO 
and STEP. The GO command starts execution. The STEP command lets 
you execute a specified number of source lines or instructions. 
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The GO Command 


The GO command starts program execution, which continues until forced 
to stop. You will probably use the GO command most often in con- 
junction with breakpoints, tracepoints, and watchpoints. If you set a 
breakpoint in the path of execution and then type the GO command (or 
press the comma key on the keypad, which executes the GO command), 
execution will be suspended when the program reaches that breakpoint. If 
you set a tracepoint, the path of execution through that tracepoint will be 
monitored. If you set a watchpoint, execution will be suspended when the 
value of the watched variable changes. 


You can also use the GO command to test for an exception condition or 
an infinite loop. If an exception condition that is not handled by your pro- 
gram occurs, the debugger will take over and display the DBG> prompt 
so that you can issue commands. If you are using screen mode, the 
pointer in the source display will indicate where execution stopped. You 
can then use the SHOW CALLS command (explained in Section 5.3.5.2) 
to identify the currently active routine calls (the call stack). 


In the case of an infinite loop, the program will not terminate, so the 
debugger prompt will not reappear. To obtain the prompt, interrupt the 
program by pressing CTRL/Y and then issue the DCL command DEBUG. 
You can then look at the source display and a SHOW CALLS display to 
locate the PC. 


The STEP Command 


The STEP command (which you can use either by typing STEP or by 
pressing the keypad 0 key) allows you to execute a specified number 

of source lines or instructions, or to execute the program to the next 
instruction of a particular kind, for example, to the next CALL instruction. 


By default, the STEP command executes a single source line at a time. In 
the following example, the STEP command executes one line, reports the 
action (“stepped to ... ”), and displays the line number (27) and source 
code of the next line to be executed: 


DBG> STEP 

stepped to TEST\COUNTER\,LINE 27 
27: X=Kr+i 

DBG> 
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The PC is now at the first machine code instruction for line 27 of the 
module TEST; line 27 is in COUNTER, a routine within the module TEST. 
"TEST\COUNTER\%LINE 27" is a path name. The debugger uses path 
names to refer to symbols. (However, you do not need to use a path 
name in referring to a symbol, unless the symbol is not unique; in that 
case, the debugger will issue an error message. See Section 5.3.7.2 for 
more information on resolving multiply-defined symbols.) 


You can specify a number of lines for the STEP command to execute. In 
the following example, the STEP command executes three lines: 


DBG> STEP 3 


Note that only those source lines for which code instructions were gener- 
ated by the compiler are recognized as executable lines by the debugger. 
The debugger skips over any other lines—for example, comment lines. 


Also, if a line has more than one statement on it, the debugger will 
execute all the statements on that line as part of the single step. 


You can specify different stepping modes, such as stepping by instruction 
rather than by line (SET STEP INSTRUCTION). To resume to the default 
behavior, issue the SET STEP LINE command. Also, by default, the 
debugger steps over called routines—execution is not suspended within a 
called routine, although the routine is executed. By issuing the SET STEP 
INTO command, you tell the debugger to suspend execution within called 
routines as well as within the currently executing module. To resume the 
default behavior, issue the SET STEP OVER command. 


5.3.5.2 Determining the Current Location of the Program Counter 


The SHOW CALLS command lets you determine the current location of 
the program counter (PC) (for example, after returning to the debugger 
following a CTRL/Y interrupt). The command shows a traceback that 
lists the sequence of calls leading to the currently executing routine. For 


example: 
DBG> SHOW CALLS 

module name routine name line rel PC abs PC 
*TEST PRODUCT 18 00000009 0000063C 
*TEST COUNTER 47 00000009 00000647 
*MY_PROG MY_PROG 21 Q0O000000D 00000653 
DBG> 
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For each routine (beginning with the currently executing routine), the 
debugger displays the following information: 


e The name of the module that contains the routine 
e The name of the routine 


e The line number at which the call was made (or at which execution is 
suspended, in the case of the current routine) 


e The corresponding PC addresses (the relative PC address from the 
start of the routine and the absolute PC address of the program) 


This example indicates that execution is currently at line 18 of routine 
PRODUCT (in module TEST), which was called from line 47 of routine 
COUNTER (in module TEST), which was called from line 21 of routine 
MY_PROG (in module MY_PROG). 


5.3.5.3 Suspending Program Execution 


The SET BREAK command lets you select breakpoints, which are locations 
at which the program will stop running. When you reach a breakpoint, 
you can issue commands to check the call stack, examine the current 
values of variables, and so on. 


A typical use of the SET BREAK command is illustrated in the following 
example: 


DBG> SET BREAK COUNTER 
DBG> GO 


break at TEST\COUNTER 
34: SUB COUNTER(LONG X,Y) 
DBG> 


In this example, the SET BREAK command sets a breakpoint on the 
subprogram COUNTER; the GO command starts execution. When the 
subprogram COUNTER is encountered, execution is suspended, the de- 
bugger announces that the breakpoint at COUNTER has been reached 
(“break at ... ”), displays the source line (34) where execution is sus- 
pended, and prompts you for another command. At this breakpoint, you 
could step through the subprogram COUNTER, using the STEP command, 
and use the EXAMINE command (discussed in Section 5.3.6.1) to check 
on the current values of X and Y. 
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When using the SET BREAK command, you can specify program locations 
using various kinds of address expressions (for example, line numbers, 
routine names, instructions, virtual memory addresses, byte offsets). With 
high-level languages, you typically use routine names, labels, or line 
numbers, possibly with path names to ensure uniqueness. 


Routine names and labels should be specified as they appear in the source 
code. Line numbers may be derived from either a source code display 

or a listing file. When specifying a line number, use the prefix %LINE. 
(Otherwise, the debugger will interpret the line number as a memory 
location.) For example, the next command sets a breakpoint at line 41 

of the currently executing module; the debugger will suspend execution 
when the PC is at the start of line 41. 


DBG> SET BREAK %LINE 41 


Note that you can set breakpoints only on lines that resulted in machine 
code instructions. The debugger warns you if you try to do otherwise 
(for example, on a comment line). If you want to pick a line number in 
a module other than the one currently executing, you need to specify the 
module’s name in a path name. For example: 


DBG> SET BREAK SCREEN_IO\%LINE 58 


You do not always have to specify a particular program location, such as 
line 58 or COUNTER, to set a breakpoint. You can set breakpoints on 
events, such as exceptions. You can use the SET BREAK command with 
a qualifier, but no parameter, to break on every line, or on every CALL 
instruction, and so on. For example: 


DBG> SET BREAK/LINE 
DBG> SET BREAK/CALL 


You can conditionalize a breakpoint (with a WHEN clause) or specify that 
a list of commands be executed at the breakpoint (with a DO clause on the 
debugger command). For example, the next command sets a breakpoint on 
the label LOOP3. The DO (EXAMINE TEMP) clause causes the value of 
the variable TEMP to be displayed whenever the breakpoint is triggered. 


DBG> SET BREAK LOOP3 DO (EXAMINE TEMP) 
DBG> GO 


break at COUNTER\LOOP3 

37: LOOP3: FOR I = 1 TO 10 
COUNTER\TEMP : 284.19 
DBG> 
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To display the currently active breakpoints, type the SHOW BREAK 
command: 


DBG> SHOW BREAK 
breakpoint at SCREEN_IO\%LINE 58 
breakpoint at COUNTER\LOOP3 

do (EXAMINE TEMP) 


DBG> 


To cancel a breakpoint, type the CANCEL BREAK command, specifying 
the program location exactly as you did when setting the breakpoint. The 
CANCEL BREAK/ALL command cancels all breakpoints. 


5.3.5.4 Tracing Program Execution 


The SET TRACE command lets you select tracepoints, which are locations 
for tracing the execution of your program without stopping its execution. 
After setting a tracepoint, you can start execution with the GO command 
and then monitor the PC’s path, checking for unexpected behavior. By 
setting a tracepoint on a routine, you can also monitor the number of 
times the routine is called. 


As with breakpoints, every time a tracepoint is reached, the debugger 
issues a message and displays the source line. It can also display other 
information that you have specified (as shown in the last example in this 
section, in which the value of a specified variable is displayed). However, 
at tracepoints, unlike breakpoints, the program continues executing, and 
the debugger prompt is not displayed. For example: 


DBG> SET TRACE COUNTER 
DBG> GO 


trace at TEST\COUNTER 
34: SUB COUNTER(LONG X,Y) 


When using the SET TRACE command, you specify address expressions, 
qualifiers, and optional clauses exactly as with the SET BREAK command. 
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The /LINE qualifier causes the SET TRACE command to trace every line 
and is a convenient means of checking the execution path. By default, 
lines are traced within all called routines as well as the currently execut- 
ing routine. If you do not want to trace system routines or routines in 
shareable images, use the /NOSYSTEM or /NOSHARE qualifiers. For 
example: 


DBG> SET TRACE/LINE/NOSYSTEM/NOSHARE 


The /SILENT qualifier suppresses the trace message and source code 
display. This is useful when you want to use the SET TRACE command 
to execute a debugger command at the tracepoint. For example: 


DBG> SET TRACE\SILENT %LINE 83 DO (EXAMINE STATUS) 
DBG> GO 


SCREEN_IO\CLEAR\STATUS : ‘OFF' 


5.3.5.5 Monitoring Changes in Variables 


The SET WATCH command lets you set watchpoints that will be moni- 
tored continuously as your program executes. 


If the program modifies the value of a watched variable, the debugger 
suspends execution and displays the old and new values. 


DBG> SET WATCH TOTAL 


Subsequently, every time the program modifies the value of TOTAL, the 
watchpoint is triggered. The debugger monitors watchpoints continuously 
during program execution. 


The next example shows what happens when your program modifies the 
contents of a watched variable. 
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DBG> SET WATCH TOTAL 
DBG> GO 


watch of SCREEN_IO\TOTAL\%LINE 13 
13: TOTAL = TOTAL + 1 
old value: 16 
new value: 17 
break at SCREEN_IO.%LINE 14 
14: CALL Pop_rtn (TOTAL) 
DBG> 


In this example, a watchpoint is set on the variable TOTAL and the GO 
command starts execution. When the value of TOTAL changes, execution 
is suspended. The debugger announces the event (“watch of ... ”), 
identifying where TOTAL changed (line 13) and the associated source 
line. The debugger then displays the old and new values and announces 
that execution has been suspended at the start of the next line (14). (The 
debugger reports “break at... ”, but this is not a breakpoint; it is still 
the effect of the watchpoint.) Finally, the debugger prompts for another 
command. 


When a change in a variable occurs at a point other than the start of a 
source line, the debugger gives the line number plus the byte offset from 
the start of the line. 


5.3.6 Examining and Manipulating Data 
This section explains how to use the EXAMINE, DEPOSIT, and 


EVALUATE commands to display and modify the contents of variables, 
and evaluate expressions in VAX BASIC programs. 
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5.3.6.1. Displaying the Values of Variables 


To display the current value of a variable, use the EXAMINE command as 
follows: 


DBG>EXAMINE variable_name 


The debugger recognizes the compiler-generated data type of the specified 
variable and retrieves and formats the data accordingly. The following 
examples show some uses of the EXAMINE command. 


Examine a string variable: 


DBG> EXAMINE EMPLOYEE_NAME 
PAYROLL\EMPLOYEE_NAME: "Peter C. Lombardi" 
DBG> 


Examine three integer variables: 


DBG> EXAMINE WIDTH, LENGTH, AREA 
SIZE\WIDTH: 4 

SIZE\LENGTH: 7 

SIZE\AREA : 28 

DBG> 


Examine a two-dimensional array of integers (three per dimension): 


DBG> EXAMINE INTEGER_ARRAY 
PROG2\ INTEGER_ARRAY 


(0,0): 27 

(0,1): 31 

(0,2): 12 

(1,0): 15 

(1,1): 22 

(1,2): 18 
DBG> 


Examine element 4 of a one-dimensional string array: 


DBG> EXAMINE CHAR_ARRAY(4) 
PROG2\CHAR_ARRAY (4): 'm' 
DBG> 


Note that the EXAMINE command can be used with any kind of address 
expression (not just a variable name) to display the contents of a program 
location. The debugger associates certain default data types with untyped 
locations. You can override the defaults for typed and untyped locations 
if you want the data to be interpreted and displayed in some other data 
format. The debugger supports the data types and operators of VAX 
BASIC including RECORDs and RFAs. 
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See Section 5.3.6.3 for an explanation of how the EXAMINE and the 
EVALUATE commands differ. 


5.3.6.2 Changing the Values of Variables 
To change the value of a variable, use the DEPOSIT command as follows: 
DBG>DEPOSIT variable_name = value 
The DEPOSIT command is like an assignment statement in VAX BASIC. 


In the following examples, the DEPOSIT command assigns new values 
to different variables. The debugger checks that the value assigned, 
which may be a language expression, is consistent with the data type and 
dimensional constraints of the variable. 


Deposit a string value (it must be enclosed in quotation marks or 
apostrophes): 


DBG> DEPOSIT PARTNUMBER = "WG-7619.3-84" 
Deposit an integer expression: 
DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10 


Deposit element 12 of an array of characters (you cannot deposit an entire 
array aggregate with a single DEPOSIT command, only an element): 


DBG> DEPOSIT C_ARRAY(12) = 'K' 


You can specify any kind of address expression, not just a variable name, 

with the DEPOSIT command (as with the EXAMINE command). You can 
override the defaults for typed and untyped locations if you want the data 
to be interpreted in some other data format. 


5.3.6.3 Evaluating Expressions 


To evaluate a language expression, use the EVALUATE command as 
follows: 


DBG> EVALUATE lang _exp 


The debugger recognizes the operators and expression syntax of the 
currently set language. In the following example, the value 45 is assigned 
to the integer variable WIDTH; the EVALUATE command then obtains the 
sum of the current value of WIDTH plus 7: 
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DBG> DEPOSIT WIDTH = 45 
DBG> EVALUATE WIDTH + 7 
52 

DBG> 


Following is an example of how the EVALUATE and the EXAMINE 
commands are similar. When the expression following the command is a 
variable name, the value reported by the debugger is the same for either 
command: 


DBG> DEPOSIT WIDTH = 45 
DBG> EVALUATE WIDTH 

45 

DBG> EXAMINE WIDTH 
SIZE\WIDTH: 465 


Following is an example of how the EVALUATE and EXAMINE com- 
mands are different: 


DBG> EVALUATE WIDTH + 7 
52 

DBG> EXAMINE WIDTH + 7 
SIZE\WIDTH: 131584 


With the EVALUATE command, WIDTH + 7 is interpreted as a language 
expression, which evaluates to 45 + 7, or 52. With the EXAMINE com- 
mand, WIDTH + 7 is interpreted as an address expression: 7 bytes are 
added to the address of WIDTH, and whatever value is in the resulting 
address is reported (in this instance, 131584). 


5.3.6.4 Stepping Into VAX BASIC Routines 


This section provides details of the STEP/INTO command that are specific 
to VAX BASIC. 


In the following example, the debugger is waiting to proceed at source line 
2. If you issue a STEP command at this point, the debugger will proceed 
to source line 3 without stopping during the execution of the function call. 
To examine the source code in the EXTERNAL FUNCTION extfun, you 
must use the STEP/INTO command. A STEP/INTO command entered 
while the debugger has stopped at source line 2, will cause the debugger 
to display the source code for extfun and stop execution at source code 
line 63. 
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1 40 EXTERNAL REAL FUNCTION extfun (real) 
->2 a = extfun (8) 
3 PRINT a 


63 100 FUNCTION REAL extfun (a) 
extfun =a * 3 
END FUNCTION 


The STEP/INTO command is useful for examining external functions. 
However, if you use this command to stop execution at an internal 
subroutine or a DEF, the debugger steps into Run-Time Library (RTL) 
routines, providing you with no useful information. For example, in the 
following partial program, the debugger has suspended execution at source 
line 8. If you now enter a STEP/INTO command, the debugger steps into 
the relevant RTL code and informs you that no source lines are available. 


1 10 RANDOMIZE 


->8 GOSUB Print_routine 


9 STOP 

20 Print_routine: 

21 IF Competition = Done 

22 THEN PRINT "The winning ticket is #"; Winning _ticket 
23 ELSE PRINT "The game goes on." 

24 END IF 

25 RETURN 


As in the previous example, a STEP command alone will cause the 
debugger to proceed directly to source line 9. To examine the source 
code of subroutines or DEF functions, you should use the SET BREAK 
command. The SET BREAK command is described in Section 5.3.5.3. In 
this case, a breakpoint set at the label Print_routine allows you to examine 
the subroutine beginning at source line 20. 
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5.3.7 Controlling Symbol References 


In most cases, the way the debugger handles symbols is transparent to 
you. However, the following areas may require action on your part: 


¢ Module setting 
¢ Multiply-defined symbols 


5.3.7.1 Module Setting 


To facilitate symbol searches, the debugger loads symbol records from the 
executable image into a run-time symbol table (RST), where they can be 
accessed efficiently. Unless a symbol record is in the RST, the debugger 
cannot recognize or properly interpret that symbol. 


Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of 
execution. The loading process is called module setting, because all of the 
symbol records of a given module are loaded into the RST at one time. 


At debugger startup, only the module containing the image transfer ad- 
dress is set. As your program executes, whenever the debugger interrupts 
execution it sets the module surrounding the current PC location. This 
lets you reference the symbols that should be visible at the current PC 
location. 


If you try to reference a symbol in a module that has not been set, the 
debugger will warn you that the symbol is not in the RST. For example: 


DBG> EXAMINE K 


“%DEBUG-W-NOSYMBOL, symbol 'K' is not in symbol table 
DBG> 


You must then use the SET MODULE command to set the module 
containing that symbol manually: 

DBG> SET MODULE MOD3 

DBG> EXAMINE K 


MOD3\ROUT2\K: 26 
DBG> 


The SHOW MODULE command lists the modules of your program and 
identifies which modules have been set. 
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A successful FIND or GET operation must precede the DELETE operation. 
These operations make the target record available for deletion. In the 
following example, the FIND statement locates record 67 in a relative file 
and the DELETE statement removes this record from the file. Because the 
cell itself is not deleted, you can use the PUT statement to write a record 
into that cell after deleting its contents. 


FIND #1%, RECORD 67% 
DELETE #1% 


NOTE 


There is no current record after a deletion. The next record 
pointer is unchanged. 


15.6.7 Updating Records 


UPDATE writes a new record at the location indicated by the current 
record pointer. UPDATE is valid on RMS sequential, relative, and indexed 
files. 


The UPDATE statement operates on the current record, provided that you 
have write access to that record. In order to successfully update a variable- 
length record, you must know the exact size of the record you want to 
update. VAX BASIC has access to this information after a successful GET 
operation. If you have not performed a successful GET operation on the 
variable-length record, then you must specify a COUNT clause in the 
UPDATE statement that contains the record size information. 


If you are updating a variable length record, and the record that you want 
to write out is of different size than the record you retrieved, you must use 
a COUNT clause. 


An UPDATE will fail with the exception “No current record” (ERR = 131) 
if you have not previously established a current record with a successful 
GET or FIND. Therefore, when updating records you should include 
error trapping in your program to make sure all GET operations execute 
successfully. 


An UPDATE operation on a sequential file is valid only when: 


e The file containing the record is on disk 
e The new record is the same size as the one it is replacing 
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e You have established a current record via a GET or FIND operation. 
Note that COUNT defaults to the size of the current record if a GET 
was performed. If a FIND operation was used to locate the current 
record, then you must supply a COUNT value. 


The following program searches to find a record in which the L_name 
field matches the specified Search_name$. Once this record is found and 
retrieved, the Rm_num field of that record is updated; the program then 
prompts for another Search_name$. If a match is not found, VAX BASIC 
prints the message “No such record” and prompts the user for another 
Search_name$. The program ends when the user enters a null string for 
the Search_name$ value. 


Example 
20 MAP (AAA) STRING L_name = 60%, F_name = 20%, Rm_num = 8% 
30 OPEN "STU.DAT"FOR INPUT AS FILE #9%, & 
ORGANIZATION SEQUENTIAL FIXED, MAP AAA 
50 INPUT "Last name";Search_name$ 
55 Search_name$ = EDIT$(Search_name$, -1%) 
60 IF Search_name$ = "" 
THEN GOTO 32010 
END IF 
65 RESTORE #9% 
70 WHEN ERROR IN 
75 GET #9% WHILE Search_name$ <> L_name 
USE 
IF ERR=11 
THEN 
PRINT "No such record" 
CONTINUE 50 
ELSE 
EXIT HANDLER 
END IF 
END WHEN 
80 INPUT "Room number" ;Rm_num 
90 UPDATE #9% 


100 GOTO 50 

32010 CLOSE #9% 

32030 PRINT "Update complete" 
32767 END 


NOTE 


An UPDATE operation invalidates the value of the current 
record pointer. The next record pointer is unchanged. 
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When you update a record in a relative variable file, the new record can 
be larger or smaller than the record it replaces, provided that it is smaller 
than the maximum record size set for the file. When you update a record 
in an indexed variable file, the new record can also be larger or smaller 
than the record it replaces. The updated record: 


¢ Can be no longer than the maximum record size, if specified 
e Must include at least the primary key field 
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$ BASIC/LIST/DEBUG SAMPLE @ 
$ LINK/DEBUG SAMPLE @ 
$ RUN SAMPLE 


VAX DEBUG Version 4.n 


“%DEBUG-I-INITIAL, language is BASIC module set to 'SAMPLE$MAIN' © 
DBG> (STEP 2) 
NUMBER SQUARE SQUARE ROOT 
apes to SAMPLE$MAIN\{line 7 
FOR Number = 10 TO 1 STEP -1 © 
DBG> se 40 
10 100 3.16228 
“eres to SAMPLES$MAIN\ALINE 7 
FOR Number = 10 TO i STEP -1 
DBG> ene Number 


SAMPLE$MAIN\NUMBER : 10 © 
DBG> STEP 4 
10 100 3.16228 


stepped to SAMPLE$MAIN\ZLINE 7 
FOR Number = 10 TO 1 STEP -1 
DBG> se sithe Number 


SAMPLE$MAIN\NUMBER : 10 ® 
DBG> DEPOSIT Number = 9 @ 
DBG> STEP 4 

9 81 


stepped to SnmieRah atviE 7 

FOR Number = 10 TO 1 STEP -1 
DBG> ee Number 
SAMPLE$MAIN\NUMBER : 9®@ 
pac> sTeP @ 
9 81 3 
stapes to SAMPLE$MAIN\%LINE 8 

PRINT Number, Number~2, SQR(Number) @ 

DBG> ares ® 
tenes to SAMPLE$MAIN\YLINE 9 

Number = Number + 1 ® 
DBG> ee @® 


@ Compile SAMPLE.BAS with the /LIST and /DEBUG qualifiers. The 
listing file may be useful while you are in the debugging session. 
Link SAMPLE.BAS with the /DEBUG qualifier. 


The debugger identifies itself and displays the debugger prompt after 
you invoke the debugger with the RUN command. 


Step through 2 executable statements to the FOR statement. 


The headers print successfully and the program reaches the FOR 
statement. 


Step through one iteration of the loop. 
Request the contents of the variable Number. 


ol to RR © a > 


The debugger shows the contents of the loop index to be 10. 
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Step through another iteration of the loop. 
Examine the value of the loop index again. 


The debugger shows that the loop index is still 10. The loop index has 
not changed from its initial setting in the FOR statement. 


Deposit the correct value into Number. 

Step through another iteration of the loop. 

Examine the contents of Number again. 

Observe that the number has not been changed yet. 


Step through just one statement to discover what is interferring with 
the value of Number during execution of the loop. 


Observe that this statement does not affect the value of Number. 
Step through another statement in the loop. 
Observe that this statement counteracts the change in the loop index. 


6eeo @g8ee8sd 8860 


Exit from the debugger. You can now edit the program to delete line 
9 and reprocess the program. Alternatively, you could use the EDIT 
command while in the debugger environment. 


This debugging session shows that the FOR...NEXT loop index (Number) 
is not being changed correctly. An examination of the statements in the 
loop shows that the variable Number is being decreased by one during 
each execution of the FOR statement, but incremented by one with each 
execution of the loop statements. From this you can determine that the 
loop index will not change at all and the program will loop indefinitely. 
To correct the problem, you must delete the incorrect statement and 
recompile the source program. 


5.5 Debugger Command Summary 
Table 5-1 lists all of the debugger commands and any related DCL 
commands in functional groupings, along with brief descriptions. 


During a debugging session, you can get online HELP on any command 
and its qualifiers by typing the HELP command followed by the name of 
the command in question, in this format: 


HELP command 
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Table 5-1: Debugger Command Summary 


Command Description 
Starting and Terminating a Debugging Session 

a 

($) RUN Invokes the debugger if LINK/DEBUG was 
used 

($) RUN/[NO]DEBUG! Controls whether the debugger is invoked 
when the program is executed 

CTRL/Z or EXIT Ends a debugging session, executing all exit 
handlers 

QUIT Ends a debugging session without executing 
any exit handlers declared in the program 

CTRL/Y Interrupts a debugging session, returning you 
to DCL level 

CTRL/C Has the same effect as CTRL/Y, unless the 
program has a CTRL/C service routine 

($) CONTINUE! Resumes a debugging session after a CTRL/Y 
interruption 

($) DEBUG! Resumes a debugging session after a CTRL/Y 
interruption but returns you to the debugger 
prompt 

ATTACH Passes control of your terminal from the 


current process to another process (similar to 
the DCL command ATTACH) 


SPAWN Creates a subprocess; lets you issue DCL 
commands without interrupting your debug- 
ging context (similar to the DCL command 
SPAWN) 


‘this is a DCL command, not a debugger command. 
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Table 5-—1 (Cont.): Debugger Command Summary 


Command 


Description 


Controlling and Monitoring Program Execution 


GO 
STEP 


SET 
SHOW 


SET 
SHOW BREAK 
CANCEL 


{ \ STEP 
SET 
SHOW TRACE 
CANCEL | 


SET 
SHOW WATCH 
CANCEL 


SET \ EXCEPTION 
CANCEL 


SHOW CALLS 
SHOW STACK 


BREAK 


CALL 


Starts or resumes program execution 


Executes the program up to the next line, 
instruction, or specified instruction 


Establishes or displays the default qualifiers 
for the STEP command 


Sets, displays, or cancels breakpoints 


Sets, displays, or cancels tracepoints 


Sets, displays, or cancels watchpoints 


Sets or cancels exception breakpoints 


Identifies the currently active routine calls 


Gives additional information about the 
currently active routine calls 


Calls a routine 


Examining and Manipulating Data 


EXAMINE 
DEPOSIT 


EVALUATE 
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Displays the value of a variable or the con- 
tents of a program location 


Changes the value of a variable or the 
contents of a program location 


Evaluates a language or address expression 


Table 5-1 (Cont.): Debugger Command Summary 


Command 


Description 


Controlling Type Selection and Symbolization 


SET 
SHOW RADIX 


CANCEL 


SET 

SHOW TYPE 
CANCEL 

SET MODE [NO]G_FLOAT 


SET MODE [NO]LINE 


SET MODE [NO]SYMBOLIC 


SYMBOLIZE 


Establishes the radix for data entry and 
display, displays the radix, or restores the 
radix 


Establishes the type to be associated with 
untyped program locations, displays the type, 
or restores the type 


Controls whether double-precision floating- 
point constants are interpreted as G_FLOAT 
or D_FLOAT 


Controls whether code locations are displayed 
in terms of line numbers or routine-name + 
byte offset 


Controls whether code locations are displayed 
symbolically or in terms of numeric addresses 


Converts a virtual address to a symbolic 
address 


Controlling Symbol Lookup 


SHOW SYMBOL 
SET . 
SHOW MODULE 
CANCEL 
SET 
SHOW IMAGE 
CANCEL 

SET MODE [NO]DYNAMIC 


ALLOCATE 


SET 
SHOW SCOPE 


CANCEL 


Displays symbols in your program 
Sets a module by loading its symbol records 


into the debugger’s symbol table, identifies a 
set module, or cancels a set module 


Sets a shareable image by loading data 
structures into the debugger’s symbol table, 
identifies a set image, or cancels a set image 


Controls whether or not modules are set 
automatically when the debugger interrupts 
execution 


Expands the debugger’s memory pool to let 
you set more modules 


Establishes, displays, or restores the scope for 
symbol lookup 
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Table 5-1 (Cont.): Debugger Command Summary 


Command 


TYPE 
EXAMINE/SOURCE 


SET 
SHOW SOURCE 


CANCEL 


SEARCH 

SET 
EAR 

{ SHOWS oe 

{ ser MAX_SOURCE_ 
SHOW Jf FILES 
SET 

{ ae \ MARGINS 


SET MODE [NO]SCREEN 
SET MODE [NO]SCROLL 


DISPLAY 


SET 
SHOW DISPLAY 


CANCEL 


SET 

SHOW WINDOW 
CANCEL 

SELECT 

SHOW SELECT 


SCROLL 
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Description 


Displaying Source Code 


Displays lines of source code 


Displays the source code at the location 
specified by the address expression 


Creates, displays, or cancels a source directory 
search list 


Searches the source code for the specified 
string 

Establishes or displays the default qualifiers 
for the SEARCH command 


Establishes or displays the maximum number 
of source files that may be kept open at one 
time 

Establishes or displays the left and right 
margin settings for displaying source code 


Using Screen Mode 


Enables or disables screen mode 


Controls whether an output display is updated 
line by line or once per command 


Modifies an existing display 


Creates, identifies, or deletes a display 


Creates, identifies, or deletes a window 
definition 
Selects a display for a display attribute 


Identifies the displays selected for each of the 
display attributes 


Scrolls a display 


Table 5-1 (Cont.): Debugger Command Summary 
Command Description 


Using Screen Mode 


SAVE Saves the current contents of a display into 
another display 

EXTRACT Saves a display or the current screen state into 
a file 

EXPAND Expands or contracts a display 

MOVE Moves a display across the screen 

SET } . 
TERMINAL Establishes or displays the height and width 
Nec wet TER play g 


of the screen 
CTRL/W or DISPLAY/REFRESH _ Refreshes the screen 


Editing Source Code 


EDIT Invokes an editor during a debugging session 
SET \ Establishes or identifies the editor invoked b 
| oe } EDITOR y 


the EDIT command 


Defining Symbols 


DEFINE Defines a symbol as an address, command, or 
value 
DELETE or UNDEFINE Deletes symbol definitions 
{ SET \ DEFINE Establishes or displays the default qualifier for 
SHOW. the DEFINE command 
SHOW SYMBOL/DEFINED Identifies symbols that have been defined 


Using Keypad Mode 


SET MODE [NO]KEYPAD Enables or disables keypad mode 
DEFINE/KEY Creates key definitions 
DELETE/KEY or UNDEFINE/KEY Deletes key definitions 
SET } ‘ i ds : 
KEY Establishes the key definition state or displays 
{ SHOW > Bre 


key definitions 
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Table 5—1 (Cont.): Debugger Command Summary 


Command 


Description 


Using Command Procedures and Log Files 


DECLARE 


SET 
L 
{sow } 49° 


SET OUTPUT [NO]LOG 

SET OUTPUT [NO]SCREEN 
LOG 

SET OUTPUT [NO]VERIFY 


SHOW OUTPUT 


SET \ ie 
{ oi p AISIGN 


@file-spec 


Defines parameters to be passed to command 
procedures 


Specifies or identifies the debugger log file 


Controls whether a debugging session is 
logged 


Controls whether, in screen mode, the screen 
contents are logged as the screen is updated 


Controls whether debugger commands are 
displayed as a command procedure is executed 


Displays the current output options estab- 
lished by the SET OUTPUT command 


Establishes or displays the default file speci- 
fication that the debugger uses to search for 
command procedures 


Executes a command procedure 


Using Control Structures 


IF 

FOR 
REPEAT 
WHILE 
EXITLOOP 


Executes a list of commands conditionally 
Executes a list of commands repetitively 
Executes a list of commands repetitively 
Executes a list of commands conditionally 


Exits an enclosing WHILE, REPEAT, or FOR 
loop 


Miscellaneous Commands 


SET OUTPUT [NO]TERMINAL 


{ SET \ LANGUAGE 


SHOW 
{ SET } EVENT_ 
SHOW ‘FACILITY 
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Controls whether debugger output is displayed 
or suppressed, except for diagnostic messages 


Establishes or displays the current language 


Establishes or identifies the current run-time 
facility for language-specific events 


Table 5-1 (Cont.): Debugger Command Summary 


Command Description 
Miscellaneous Commands 
SHOW EXIT_-HANDLERS Identifies the exit handlers declared in the 
program 

{ SET \ TASK Modifies the tasking environment or displays 
SHOW task information 
DISABLE Disables the delivery of ASTs in the program, 
eee AST enables the delivery of ASTs, or identifies 


whether delivery is enabled or disabled 
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VAX BASIC PROGRAMMING CONCEPTS 


Chapter 6 


Getting Started with VAX BASIC 


A VAX BASIC program is a series of instructions for the VAX BASIC 
compiler. These instructions, no matter how varied, are all built using the 
same fundamental elements of VAX BASIC. This chapter describes the 
elements or building blocks of VAX BASIC. 


6.1 Line Numbers 


Traditionally, BASIC programs consisted of statements preceded by unique 
line numbers. However, VAX BASIC gives you the option of developing 
programs with traditional line numbers or programs with no line numbers 
at all. 


6.1.1 Programs with Line Numbers 


If you use line numbers in your programs, you must follow these rules: 


A line number must be a unique integer between 1 and 32767 (If your 
program has duplicate line numbers, the last line with that number 
replaces the previous one). 


A line number must begin in the first character position on the line. 


A line number can contain leading zeros; however, embedded spaces, 
tabs, and commas are invalid in line numbers. 


There must be a line number on the first line of the program 


If a source file contains subprograms, then each subprogram must 
begin on a numbered line. 
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e The line number of a subprogram must be greater than that of any 
preceding subprogram line number. 


e =6Text following an END, END SUB, or END FUNCTION statement 
must begin on a numbered line. 


Note that in a multiple-unit program with line numbers, any comments 
following an END, END SUB, or END FUNCTION statement become a 
part of the previous subprogram during compilation unless they begin on 
a numbered line. This is not the case in multiple-unit programs without 
line numbers. 


Although line numbers are not required, you may want to use them on 
every line that can cause a run-time error, depending on the type of error 
handling you use. See Chapter 17 for more information about handling 
run-time errors. 


6.1.2 Programs Without Line Numbers 


If you do not use line numbers in your programs, you must follow these 
rules: 


e Use a text editor to enter and edit the program; you cannot enter 
programs without line numbers directly in the environment. 

¢ No line numbers are allowed anywhere in the program module. 

e The ERL function is not allowed. 

¢ Do not use the RESUME statement with a line number as a target. 

¢ REM statements are not allowed. 


e Ifa source file contains subprograms, any text following an END, END 
SUB, or END FUNCTION statement must begin on a new physical 
line. 


¢ Other files cannot be appended, because appended files must contain 
at least one line number. 


Note that in a multiple-unit program without line numbers, any comments 
following an END, END SUB, or END FUNCTION statement become a 
part of the next subprogram during compilation (unless there is no next 
subprogram). This is not the case in multiple-unit programs with line 
numbers. 
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Note that you can avoid all of these restrictions by placing a line number 

on the first line of your program; no additional line numbers are required. 
The line number on the first program line causes the VAX BASIC compiler 
to compile your program as a program with line numbers. 


When you enter a program with or without line numbers, you can begin 
your program statements in the first character position on a line. While 
these statements would be considered immediate mode statements if 
entered in the BASIC environment, they are valid in a program that is 
created with a text editor. 


For example, you can enter the following program directly into the 
environment: 


Example 


10 !This is a short program that you can enter 
‘and run in the BASIC environment 
! 
PRINT "This program will convert pound weight to kilograms" 
INPUT "How many pounds" ;A 
!Here is the conversion step 
B=A * 2.2 
PRINT "For ";A;" pounds, the kilogram weight is ";B 
END 


Output 


This program will convert pound weight to kilograms 
How many pounds? 10 
For 10 pounds, the kilogram weight is 22 


In order to develop the following program, you have to use a text editor, 
and you must observe the restrictions listed above. 
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Example 


!This is a short program that does not contain any 
!VAX BASIC line numbers. 
!This program must be entered using a text editor; 


!it cannot be entered directly into the environment. 
t 


PRINT "This program converts kilogram weight to pounds" 
INPUT "How many kilograms";A 

!This is the conversion factor 

B=A/ 2.2 

PRINT "For ";A;" kilograms, the pound weight is ";B 
END 


Output 


This program converts kilogram weight to pounds 
How many kilograms? 11 
For 11 kilograms, the pound weight is 5 


Note that you can use exclamation comment fields instead of REM state- 
ments to insert comments into programs without line numbers. An 
exclamation mark in column 1 in the environment causes the VAX BASIC 
compiler to ignore the rest of the line. You can also identify program 
statements in programs without line numbers by using labels. 


6.1.3 Labels 


A label is a 1- to 31-character identifier that you use to identify a block 
of statements. All label names must begin with a letter; the remaining 
characters, if any, can be any combination of letters, digits, dollar signs 
($), underscores (_) or periods (.). 


Labels have two advantages over line numbers: 


¢ Meaningful label names provide documentation. 
e¢ You can use labels in programs with or without line numbers. 


When you use a label to mark a program location, you must end the 
label with a colon (:). The colon is used to show that the label name is 
being defined instead of referenced. When you reference the label, do not 
include the colon. In the following example, the label names end with 
colons when they mark a location, but the colons are not present when 
the labels are referenced. 
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Example 


OPTION TYPE = EXPLICIT ! Require declarations 
DECLARE INTEGER A 


Outer_decision: 


IF A <> B 
THEN 


Inner_decision: 
IF B=C 
THEN 
A=A+1 
GOTO Outer_loop 
ELSE 
B=B+e+i 
GOTO Inner_loop 
END IF 
END IF 


Labels have no effect on the order in which program lines are executed; 
they are used to identify a statement or block of statements. 


6.1.4 Continuation of Long Program Statements 


If a program line is too long for one line of text, you can continue the 
program line by typing an ampersand (&) and pressing the RETURN key 
at the end of the line. Note that only spaces and tabs are valid between 
the ampersand and the carriage return. 


A single statement that spans several text lines requires an ampersand at 
the end of each continued line. For example: 


OPEN "SAMPLE.DAT" AS FILE #2%, & 
SEQUENTIAL VARIABLE, & 
RECORDSIZE 80% 


In an IF...THEN...ELSE construction, statement separators are not neces- 
sary. If a continuation line begins with THEN or ELSE, then no statement 
separator is necessary. Similarly, in a line following a THEN or ELSE, 
there is no statement separator. 
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Example 


IF (A$ = B$) 
THEN 

PRINT "The two values are equal" 
ELSE 

PRINT "The two values are different" 
END IF 


Several statements can be associated with a single program line. If there 
are several statements on one line, they must be separated by backslashes 
(\). For example: 


PRINT A \ PRINT V \ PRINT G 


Because all statements are on the same program line, any reference to this 
program line refers to all three statements. In the preceding example, VAX 
BASIC cannot execute just one of the statements without executing the 
other two. 


6.2 Identifying Program Units 


You can delimit a main program compilation unit with the PROGRAM 
and END PROGRAM statements. This allows you to identify a program 
with a name other than the file name. The program name must not 
duplicate the name of a SUB, FUNCTION, or PICTURE subprogram. 


PROGRAM Sort_out 


END PROGRAM 


If you include the PROGRAM statement in your program, the name you 
specify becomes the module name of the compiled source. This feature is 
useful when you use object libraries because the librarian stores modules 
by their module name rather than the file name. Similarly, module names 
are used by the VAX/VMS Debugger and the VAX/VMS Linker. 


For more information about PROGRAM units, see Chapter 14. 
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6.3 The VAX BASIC Character Set 


VAX BASIC uses the full ASCII character set, which includes the 
following: 

e The letters A through Z, both upper- and lowercase 

e ©The digits 0 through 9 

e Special characters 


See the VAX BASIC Reference Manual for a complete list of the ASCII 
character set and character values. 


The VAX BASIC compiler does not distinguish between upper- and 
lowercase letters, except letters inside quotation marks (called string 
literals) or letters in a DATA statement. The compiler also does not 
process characters in a REM statement or comment field. 


You can use nonprinting characters in your program, for example, in string 
literals and constants, but to do so you must do one of the following: 

e Use a predefined constant such as ESC or DEL 

¢ Use the CHR$ function to specify an ASCII value 


See Section 6.6 for more information on predefined constants. See 
Chapter 13 for more information on the CHR$ function. 


6.4 Program Documentation 


Documenting a program is the process of mixing text (comments) and code 
in a way that helps make the program more understandable. Program 
documentation does not affect the way a program executes. 


You can sprinkle comments liberally throughout a program; however, 
programs that are neatly structured need fewer comments. You can clarify 
your code by 

e Using meaningful variable names 

e Including sufficient white space 

¢ Indenting your program lines according to the structure of your code 
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In VAX BASIC, a comment field starts with an exclamation point (!) 
and ends with a carriage return. The following example contains both 
comments and program statements. VAX BASIC ignores any text that 
follows an exclamation point. 


Example 
PROGRAM sample 


{ 

: Require that all variables be declared 
1- 

OPTION TYPE = EXPLICIT 

> Set up error handler 

t- 

WHEN ERROR USE Error_routine 

'+ 


! Declarations 
- 


END PROGRAM 


You can also mix comments and code on the same line. 


Example 

DECLARE & 
INTEGER & 
Print_page, ! Current page number & 
Print_line, ! Current line number & 
Print_column ! Current column number 


In this case, VAX BASIC ignores all text between the exclamation point 
and the carriage return, with one exception: VAX BASIC still recognizes 
the ampersand. This is a continuation character that specifies that a single 
statement is being continued on the next line. Only spaces and tabs are 
valid between the ampersand and the carriage return. 


NOTE 


You can also terminate a comment field with an exclamation 
point. However, because VAX BASIC treats any text that 
follows the second exclamation point as part of your program 
code, this practice is not recommended. 
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6.5 Declarations and Data Types 


VAX BASIC offers two different methods for creating variables and 
specifying their data types: 

e Implicit data typing 

e Explicit data typing 

With implicit data typing, VAX BASIC creates and specifies a data type for 
a variable the first time you reference it in your program. With explicit 


data typing, you must use one of four declarative statements to name and 
type your program values. 


VAX BASIC has five data types: 


e Integer (INTEGER) 

e Floating-point (REAL) 

e String (STRING) 

e Packed Decimal (DECIMAL) 

e Record File Address (RFA) 

Within the INTEGER and REAL data types there are further subdivisions: 
BYTE, WORD, or LONG for INTEGER and SINGLE, DOUBLE, GFLOAT, 
or HFLOAT for REAL. Choosing one of these subtypes lets you control two 
things: 

e The amount of storage required for the value; its “container size” 

e The range and precision that the value can accept 


For more information about data types, see Chapter 2: 


6.5.1 Implicit Data Typing 


With implicit data typing, VAX BASIC creates and specifies a data type for 

a variable the first time you reference it. You specify the data type of the 

variable by a suffix on the variable name: 

e A percent sign suffix (% ) specifies the INTEGER data type. 

e A dollar sign suffix ($) specifies the STRING data type. 

e Any other ending character specifies a variable of the default data 
type. 
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The VAX BASIC default data type is SINGLE; however, you can specify 
your own default at DCL command level, inside the BASIC environment, 
or with the OPTION statement in your program. For more information 
on establishing default data types, see Chapters 3 and 4 and the OPTION 
statement in the VAX BASIC Reference Manual. 


The first time VAX BASIC references one of these variables, it creates 
a variable with that name and data type and allocates storage for that 
variable. 


In the following example, VAX BASIC creates two INTEGER variables, A% 
and B%. Even though the values assigned to these variables are REAL, 
VAX BASIC converts these values to INTEGER to match the data type 
specified for the variables. The sum of these two values is therefore 30, 
not 30.6 as it would be if the variables were named simply A and B. 


Example 
A% = 10.1 
BY = 20.5 


PRINT A% + BY 


Output 
30 


With explicit data typing, you use a declarative statement to name and 
specify a data type for your program values. 


6.5.2 Explicit Data Typing 


VAX BASIC has four declarative statements. These statements create 
variables and allocate storage. The statements are 


e DECLARE 

e DIMENSION 
¢ COMMON 

e MAP 
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The statement you choose depends on the way in which you will use the 
variables: 


e DECLARE and DIMENSION allocate dynamic storage for variables; 
storage is allocated when the program executes. 


¢ COMMON and MAP statements allocate storage for variables stati- 
cally; storage is allocated when the program is compiled. 


The difference between these types of storage is most apparent in the case 
of strings; string variables created with DECLARE can change their length 
during program execution, while those created with MAP and COMMON 
remain fixed in length. All four declarative statements associate a data 
type with a variable. For more information, see Chapter 9. 


6.6 Constants 


A constant is a value that does not change during program execution. 
Constants can be either literals or named constants, and can be of any 
data type except RFA. You can use the DECLARE CONSTANT statement 
to create named constants. Constants can be of the following types: 


e Integer 
e = Floating-point 
e String 


In addition, VAX BASIC provides predefined constants that are useful for: 


e Formatting program output to improve clarity 
e Making source code easier to understand 


e¢ Using nonprinting characters without having to look up their ASCII 
values 


Table 6-1 lists all of the VAX BASIC predefined constants. 
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Table 6-1: Predefined Constants 


Decimal 
ASCII 
Constant Value Purpose 
BEL (Bell) 7 Sounds the terminal bell 
BS (Backspace) 8 Moves cursor one position to the left 
HT (Horizontal Tab) 9 Moves cursor to the next horizontal tab stop 
LF (Line Feed) 10 Moves cursor to the next line 
VT (Vertical Tab) 11 Moves cursor to the next vertical tab stop 
FF (Form Feed) 12 Moves cursor to the start of the next page 
CR (Carriage Return) 13 Moves cursor to the beginning of the current 
line 
SO (Shift Out) 14 Shifts out for communications networking, 
screen formatting, and alternate graphics 
SI (Shift In) 15 Shifts in for communications networking, 
screen formatting, and alternate graphics 
ESC (Escape) 27 Marks the beginning of an escape sequence 
SP (Space) 32 Inserts one blank space in program output 
DEL (Delete) 127 Deletes the last character entered 
PI None Represents the number PI with the precision 


of the default floating-point data type 


These predefined constants simplify the task of using nonprinting charac- 
ters in your programs. For example, the following statement causes a bell 
to sound on your terminal: 


PRINT BEL 


The following statement prints and underlines a word on a hard copy 
terminal: 


PRINT "NAME:" + BS + BS + BS + BS + BS + "_____ - 


To print and underline the same word on a VT100 series video display 
terminal, use the following statement. Note that the “m” in the following 
example must be lowercase: 


PRINT ESC + "[4mNAME:" + ESC + "[Om" 
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You can also create your own predefined constants with the DECLARE 
CONSTANT statement. The following statements define and print a 
constant that prints and underlines the string “NAME:”: 


DECLARE STRING CONSTANT Underlined_word = ESC + "[4mNAME:" + ESC + "(Om" 
PRINT Underlined_word 


For more information on constants, see Chapter 9 and the VAX BASIC 
Reference Manual. 


6.7 Variables 


A variable is a unique storage location that is referred to by a variable 
name. The most important property of variables is that their values can 
change during program execution. Each named location can hold only one 
value at a time. 


A variable name can have up to 31 characters. The name must begin with 
a letter; the remaining characters, if any, can be any combination of letters, 
digits, dollar signs ($), underscores (_), and periods (.). 


Variables can be grouped in an orderly series under a single name. These 
groups are called arrays. You refer to a single variable in an array by using 
one or more subscripts that specify the variable’s position in the array. 


6.7.1 Floating-Point Variables 


A floating-point variable is a named location that stores a single floating- 
point value. The storage space required to hold the value depends on 

the variable’s REAL subtype. For example, each SINGLE floating-point 
variable requires 32 bits (4 bytes) of storage, while each DOUBLE floating- 
point variable requires 64 bits (8 bytes) of storage. 


Note that if any integer value is assigned to a floating-point variable, VAX 
BASIC converts the value to a floating-point number. 
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6.7.2 Integer Variables 


An integer variable is a named location that stores a whole number. 

The storage space required to hold the value depends on the variable’s 
INTEGER subtype. For example, each BYTE integer variable requires 8 
bits (1 byte) of storage, while each LONG integer variable requires 32 bits 
(4 bytes) of storage. 


If you assign a floating-point value to an integer variable, VAX BASIC 
truncates the fractional portion of the value; it does not round to the 
nearest integer. In the following example, VAX BASIC assign the value -5 
to the integer variable, not —6. 


BA = -5.7 


6.7.3 Packed Decimal Variables 


A packed decimal (DECIMAL data type) variable is made up of several 

storage locations, the number of which depends on the declared size of 

the variable. However, a packed decimal variable is still referred to by a 
single variable name. 


When you declare a packed decimal variable, you specify the total number 
of digits and the number of digits to the right of the decimal place that 
you want. 


The following statement creates a packed decimal variable named 
My_decimal, which can contain up to eight digits: six digits to the left of 
the decimal point, and two digits to the right of the decimal point. 


OPTION TYPE = EXPLICIT 
DECLARE DECIMAL (8,2) My_decimal 


Packed decimal numbers are most useful for dollars-and-cents calculations. 


6.7.4 String Variables 


Unlike some of the numeric variables described so far, a string variable 
does not correspond to a single location in memory because a string 
variable is more likely to exceed a single location in memory. Therefore, 
the value of a string variable may be contained in any number of memory 
locations. However, a string variable is still referred to by a single name: 


DECLARE STRING Employee_name 
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6.7.5 Subscripted Variables 


A subscripted variable is a floating-point, integer, packed decimal, RFA, or 
string variable that is part of an array. Chapter 8 describes arrays in detail. 


An array is a set of data organized in one or more dimensions. A one- 
dimensional array is called a list or vector. A two-dimensional array is 
called a matrix. VAX BASIC arrays can have up to 32 dimensions. 


When you create an array, its size is determined by the number of di- 
mensions and the maximum size, called the bound, of each dimension. 
Subscripts begin by default with 0, not 1. That is, when calculating the 
number of elements in a dimension, you count from zero to the bound 
specified. 


The following DECLARE statement creates an 11 by 11 array of integers 
(11 by 11 rather than 10 by 10, because VAX BASIC arrays are zero-based 
by default). Therefore the array contains a total of 121 array elements. 


DECLARE INTEGER My_array (10, 10) 


There are many applications where you need to reference data for a 
particular range of values. In order to do this, VAX BASIC lets you specify 
a lower bound other than zero for your arrays. The following example 
declares an array containing the birth rates for the years between 1945 
and 1985: 
OPTION TYPE = EXPLICIT, & 

SIZE = REAL SINGLE 


DECLARE REAL Birth_rates(1945 TO 1985) 


Subscripts define the position of an element in an array; the expression 
Birth_rates(1970) refers to the 26th value (represented by 1970) of the 
array Birth_rates. For more information on arrays, see Chapter 8. 


NOTE 


By default, the compiler signals an error if a subscript is larger 
than the allowable range. Also, the amount of storage that the 
system can allocate depends on available memory. Therefore, 

very large arrays may cause an internal allocation error. 


VAX BASIC sets variables to zero or null values at the start of program 
execution; that is, it initializes them. Variables initialized by VAX BASIC 
include the following. 


Getting Started with VAX BASIC 6-15 


e Numeric variables and array elements (except those in MAP or 
COMMON statements). 


e String variables and array elements (except those in MAP or 
COMMON statements). 


¢ Variables in subprograms. Subprogram variables (except those in 
MAP or COMMON statements) are initialized to zero or the null 
string each time the subprogram is called. 


e Arrays created with an executable DIMENSION statement. VAX 
BASIC reinitializes the array each time the array is redimensioned. 


6.8 Keywords and Reserved Words 


Keywords are elements of the VAX BASIC language. Keywords that are 
not reserved can be used as user identifiers such as labels, variable or 
constant names, or names of MAP or COMMON areas. Depending upon 
the location of the keyword in your program statement, the compiler will 
treat it as either a keyword or a user identifier. Your VAX BASIC programs 
use keywords and reserved words to 


e Define data 
e Perform operations 
¢ Invoke functions 


See the VAX BASIC Reference Manual for a list of VAX BASIC keywords 
and reserved words. 


Keywords determine whether the statement is executable or nonex- 
ecutable. Executable statements such as PRINT, GOTO, and READ 
perform operations. Nonexecutable statements such as DATA, DECLARE, 
and REM, describe the characteristics and arrangement of data, usage 
information, and comments. 


Every statement except LET and empty statements (lines that start with an 
exclamation point) must begin with a keyword. A VAX BASIC keyword 
cannot have embedded spaces or be split across lines of text. There 

must be a space or tab between the keyword and any other variables or 
operators. 


There are also phrases of keywords. In this case, the spacing requirements 
vary. 
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6.9 Operands, Operators and Expressions 


An operand is anything that contains a value. An operand can be a 
scalar, a subscripted variable, a named constant, a literal, and so on. An 
operator specifies a procedure to be carried out one or more operands. An 
expression consists of operands separated by operators. 


VAX BASIC has four types of operators: 
e = Arithmetic 


e String 
e = Relational 
¢ Logical 


When combined with operands, these operators can produce 


e Numeric expressions 
e String expressions 
e Conditional expressions 


For more information about operands, operators, and expressions, see the 
VAX BASIC Reference Manual. 


6.10 Assignment Statements 


VAX BASIC has four statements that assign values to variables: 


e LET 
¢ INPUT 
e LINPUT 


¢ INPUT LINE 


LET and INPUT statements allow you to assign values to any type of 
variable, while LINPUT and INPUT LINE allow you to assign values to 
string variables. For example: 


LET A = 1.25 
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LET is an optional keyword. You can assign a value to more than one 
variable at a time, although this is not recommended. Instead, you should 
use a separate assignment statement each time you assign a value to a 
variable. 


Whenever you assign a value to a numeric variable, VAX BASIC converts 
the value to the data type of the variable. If you assign a floating-point 
value to an integer variable, VAX BASIC truncates the value at the decimal 
point. If you assign an integer value to a floating-point variable, VAX 
BASIC converts the value to floating-point format. 


You can also assign values to variables with the DATA and READ state- 
ments; however, this method requires that you know all input data values 
while you are coding your program. 


The INPUT, LINPUT, and INPUT LINE statements all assign values in 
the context of data being read into the program. These statements are 
discussed in Chapter 7. 
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Chapter 7 


Simple Input and Output 


This chapter explains how to use the VAX BASIC statements that move 
data to and from your program. 


7.1 Program Input 


VAX BASIC programs receive data in three ways: 


e You can enter data interactively while the program runs. You do this 
with the INPUT, INPUT LINE, and LINPUT statements. 


e If you know all the information your program will require, you can 
enter it as you write the program. You do this with the READ, DATA, 
and RESTORE statements, or you can name constants with the known 
values. 


e You can read data from files outside the program. You do this with 
the INPUT #, INPUT LINE #, and LINPUT # statements. 


The following sections describe how to use these statements in detail. 


7.1.1 Providing Input Interactively 


The INPUT, INPUT LINE, and LINPUT statements prompt a user for data 
while the program runs. 
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7.1.1.1 


The INPUT Statement 


The INPUT statement interactively prompts the user for data. You can 
use the optional prompt string to clarify the input request by specifying 
the type and number of data elements required by the program. This is 
especially useful when the program contains many variables, or when 
someone else is running your program. 


Example 


INPUT PLEASE TYPE 3 INTEGERS" ;B% ,C% ,D% 
A% = BY + C% + DY 

PRINT "THEIR SUM IS"; A% 

END 


Output 


PLEASE TYPE 3 INTEGERS? 25,50,75 [RET] 
THEIR SUM IS 150 


When your program runs, VAX BASIC stops at each INPUT, LINPUT, 

or INPUT LINE statement, prints a string prompt, if specified, and an 
optional question mark (?) followed by a space; it then waits for your 
input. By using either a comma or semicolon, you can affect the format of 
your string prompt. 


e If you have a semicolon separating the input prompt string from the 
variable, VAX BASIC prints the question mark and space immediately 
after the input prompt string. 


e If you have a comma separating the input prompt string from the 
variable, VAX BASIC prints the input prompt string, skips to the next 
print zone, and then prints the question mark and space. 


See Section 7.2.1 for more information about print zones. For more 
information on formatting string prompts, see Section 7.1.1.3. 


You must provide one value for each variable in the INPUT request. If 
you do not provide enough values, VAX BASIC prompts you again. 
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Example 
INPUT A,B 
END 


Output 
75 
76 


VAX BASIC interprets a carriage return (null input) as a zero value for 
numeric variables and as a null string for string variables. For example: 


25 
? 
These responses assign the value 5 to variable A and zero to variable B. In 


contrast, if you provide more values than there are variables, VAX BASIC 
ignores the excess. 


In the following example, VAX BASIC ignores the extra value (8). Note 
that you can type multiple values if you separate them with commas. 
Because commas separate variables in the PRINT statement, VAX BASIC 
prints each variable at the start of a print zone. 


Example 


INPUT A,B,C 
PRINT A,B,C 
END 


Output 


? 5,6,7,8[RET| 
5 6 7 


If you name a numeric variable in an INPUT statement, you must supply 
numeric data. If you supply string data to a numeric variable, VAX BASIC 
signals “Illegal number” (ERR=52). If you supply a floating-point number 
for an integer variable, VAX BASIC signals “Data format error” (ERR=50). 


If you name a string variable in an INPUT statement, you can supply 
either numbers or letters, but VAX BASIC treats the data you supply as 
a string. Because digits and a decimal point are valid text characters, 
numbers can be interpreted as strings. 
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Example 


INPUT "Please type a number"; A$ 
PRINT A$ 


Output 


Please type a number? 25.5 
25.5 


VAX BASIC interprets the response as a four-character string instead of as 
a numeric value. 


You can type strings with or without quotation marks. However, if you 
want to input a string containing a comma, you should enclose the string 
in quotation marks or use the INPUT LINE or LINPUT statement. If you 
do not, VAX BASIC treats the comma as a delimiter and assigns only part 
of the string to the variable. If you use quotation marks, be sure to type 
both beginning and ending marks. If you leave out the end quotation 
mark, VAX BASIC signals “Data format error” (ERR=50). 


7.1.1.2 The INPUT LINE and LINPUT Statements 


The INPUT LINE and LINPUT statements prompt you for string data 
while your program runs. You can respond with strings that contain 
commas, semicolons, and quotation marks, which are characters that the 
INPUT statement interprets as delimiters. 


The INPUT LINE statement accepts and stores all characters, including 
quotation marks, semicolons, and commas, up to and including the line 
terminator or terminators. LINPUT accepts all characters up to, but not 
including, the line terminator or terminators. 


In the following example, because both INPUT LINE and LINPUT treat 
your input as a string literal, VAX BASIC interprets quotation marks, 
commas, and semicolons as characters, not as string delimiters. When 
A$ is input with the INPUT LINE statement, the carriage return line 
terminator is stored as part of the string. The first PRINT statement tells 
VAX BASIC to print all three variables on one line, starting each one in 
a new print zone. However, when VAX BASIC prints the three strings, it 
prints the carriage return character at the end of string A$; this terminates 
the current line and causes B$ to begin on a new line. 


7-4 Simple Input and Output 


Example 


INPUT LINE A$ 
LINPUT B$ 

LINPUT C$ 

PRINT A$, B$, C$ 
PRINT "DONE" 

END 


Output 


? SINGLE, DOUBLE [RET | 
? "GFLOAT" 
? HFLOAT; REAL Data Types 


SINGLE, DOUBLE 
"GFLOAT" HFLOAT; REAL Data Types 
DONE 


The INPUT, INPUT LINE, and LINPUT statements can accept data from a 
terminal or a terminal-format file. See Section 7.3 for information on I/O 
to terminal-format files. 


7.1.1.3 Enabling and Disabling the Question Mark Prompt 


With the SET PROMPT statement, VAX BASIC allows you to enable and 
disable the question mark prompt. 


- By default, VAX BASIC displays the question mark prompt. For instance, 
the following example displays the default prompt string: 


Example 


INPUT "Please input 3 integer values";A%, BZ, Ch 


Output 


Please input 3 integer values? 


You can, however, disable the question mark prompt by specifying the 
SET NO PROMPT statement. 
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Example 

SET NO PROMPT 

INPUT "Please input 3 integer values";A%, BZ, C% 
Output 


Please input 3 integer values 


When you disable the question mark prompt, you can specify your own 
prompt at the end of each prompt string. The following example inserts a 
colon at the end of the prompt string. 

Example 

SET NO PROMPT 

INPUT "Please enter your name: ";Employee_name$ 

Output 


Please enter your name: 


Now, if the SET PROMPT statement is specified, VAX BASIC displays 
both the colon and a question mark: 

Example 

SET PROMPT 

INPUT "Please enter your name: ";Employee_name$ 

Output 


Please enter your name: ? 


The SET [NO] PROMPT statement is valid for INPUT, LINPUT, INPUT 
LINE, and MAT INPUT statements. If the prompt is disabled, any one of 
the following commands re-enables it: 


e The SET PROMPT statement 
e The CHAIN statement 
¢ The NEW, OLD, RUN, or SCRATCH compiler command 
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7.1.2 Providing Input from the Source Program 


The following sections describe the READ, DATA, and RESTORE state- 
ments. To use READ and DATA statements, you must know what data 
is required when writing the program. These statements do not stop to 
request data while the program runs. Therefore, your program runs faster 
than with the INPUT statements. 


The RESTORE statement lets you use the same data items more than 
once. 


7.1.2.1 The READ and DATA Statements 


The READ statement reads values from a data block. A data pointer keeps 
track of the data read. Each time the READ statement requests data, VAX 
BASIC retrieves the next available constant from a DATA statement. The 
DATA statement contains the values that the READ statement reads. In 

a DATA statement, integer constants are whole numbers; they cannot be 
followed by a percent sign. In the following example, VAX BASIC signals 
an error because the integer constants in the DATA statement contain 
percent signs. 


Example 


10 WHEN ERROR USE catch_it 
DATA 1%, 2%, 3% 
20 READ A%, BA, Ch 
END WHEN 
400 HANDLER catch_it 
PRINT "ERROR NUMBER IS "; ERR 
PRINT "ERROR AT LINE "; ERL 
PRINT "ERROR MESSAGE IS "; ERT$(ERR) 


END HANDLER 
500 END 
Output 


ERROR NUMBER IS 50 
ERROR AT LINE 20 
ERROR MESSAGE IS %Data format error 


A READ statement is not valid without at least one DATA statement. If 
your program contains a READ statement but no DATA statement, VAX 
BASIC signals the compile-time error “READ without DATA’. 


READ statements can appear either before or after their corresponding 
DATA statements. The only restriction is that the DATA statements must 
be in the same order as their corresponding READ statements. 
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You can have more than one DATA statement in a program. DATA 
statements are ignored without at least one READ statement. You can use 
an ampersand to continue a DATA statement. For example: 


10 DATA "ABRAMS", BAKER, CHRISTENSON, & 
DOBSON, “EISENSTADT", FOLEY 


Note that comment fields are not allowed in DATA statements. For 
example, the following statements cause A$ to contain the string 


“ABC!COMMENT”. 
READ A$ 
DATA ABC ! COMMENT 


When you compile a program, VAX BASIC creates one data block for 
each program unit. Each data block is local to the program or subprogram 
containing it; this means that you cannot share DATA statements between 
program modules. 


The data block contains the values in all DATA statements in that program 
unit. These values are stored in line number order. Each time VAX BASIC 
executes a READ statement, it retrieves the next value in the data block. 


VAX BASIC signals an error if you do one of the following: 


e Assign alphabetic characters to a numeric variable. VAX BASIC signals 
“Data format error” (ERR=50). 


e Have more variables in the READ statements than there are values in 
the DATA statements. VAX BASIC signals “Out of data” (ERR=57). 


VAX BASIC ignores excess data in DATA statements. 


The following example of READ and DATA mixes string and floating- 
point data types. The first READ statement reads the first data item in 
the program: “The diameter is”. The second READ statement reads the 
second data item: 40.5. 
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Example 


DATA "The diameter is" 
DATA 40.5 

READ text$ 

READ radius 

DIAMETER = PI * radius * 2 
PRINT text$; DIAMETER 

END 


Output 
The diameter is 254.469 


7.1.2.2 The RESTORE Statement 


The RESTORE statement lets you read the same data more than once. It 
has no effect without READ and DATA statements. 


RESTORE resets the data pointer to the beginning of the first DATA 
statement in the program unit. You can then read data values again. 
Consider the following program. 


Example 


10 READ B,C,D 

20 RESTORE 

30 READ E,F,G 

40 DATA 6,3,4,7,9,2 
50 END 


The READ statement in line 10 reads the first three values in the DATA 
statement: 


B=6 
C=3 
D=4 


The RESTORE statement resets the pointer to the beginning of line 40. 
During the second READ statement (line 30), the first three values are 
read again: 


E=6 
F=3 
G=4 
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Without the RESTORE statement, line 30 would assign the following 
values: 

E=7 

F=9 

G=2 


7.2 Program Output 


The PRINT statement displays data on your terminal during program 
execution. VAX BASIC evaluates expressions before displaying results. 
Note that you can also print and format data with the PRINT USING 
statement. For information about the PRINT USING statement, see 
Chapter 16. 


When you use the PRINT statement, VAX BASIC does the following: 


e Precedes positive numbers with a space and negative numbers with a 
minus sign 


e Prints a space after every number 
e Prints strings without leading or trailing spaces 
When an element in a list is not a simple variable or constant, VAX BASIC 
evaluates the expression before printing the value. 
Example 
A = 45 
B = 55 
PRINT A + B 
END 
Output 
100 


However, VAX BASIC interprets text inside quotation marks as a string 
literal. 
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A = 45 
B = 55 

PRINT "A + B" 
END 


Output 
A+B 


The PRINT statement without an expression prints a blank line. 


Example 


PRINT "This example leaves a blank line" 
PRINT 

PRINT “between two lines." 

END 


Output 


This example leaves a blank line 


between two lines. 


7.2.1 Print Zones—the Comma and the Semicolon 


A terminal line contains zones that are 14 character positions wide. The 
number of zones in a line depends on the width of your terminal: a 72- 
character line contains 5 zones, which start in columns 1, 15, 29, 43, and 
57. A 132-character line has additional print zones starting at columns 71, 
85, 99, and 113. 


The PRINT statement formats program output into these zones in different 
ways, depending on the character that separates the elements to be 
printed. If a comma precedes the PRINT item, VAX BASIC prints the item 
at the beginning of the next print zone. If the last print zone on a line is 
filled, VAX BASIC continues output at the first print zone on the next line. 
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Example 


INPUT A ,B ,C ,D ,E .F 

PRINT A ,B ,C ,D ,E ,F 

END 

Output 

? 5,10,15,20,25,30([RET] 

5 10 15 20 25 
30 


VAX BASIC skips one print zone for each extra comma between list 
elements. For example, the following program prints the value of A in the 
first zone and the value of B in the third zone. 


Example 


A=5 

B = 10 

PRINT "first zone", ,"third zone" 
PRINT A, ,B 

END 


Output 


first zone third zone 
5 10 


If you separate print elements with a semicolon, VAX BASIC does not 
move to the next print zone. In the following example, the first PRINT 
statement prints two numbers. (Printed numbers are preceded by a space 
or a minus sign and followed by one space.) The second PRINT statement 
prints two strings. 


Example 


PRINT 10; 20 
PRINT "ABC"; "XYZ" 
END 


Output 


10 20 
ABCXYZ 


Whether you use a comma or a semicolon at the end of the PRINT 
statement, the cursor remains at its current position until VAX BASIC 
encounters another PRINT or INPUT statement. In the following example, 
VAX BASIC prints the current values of X, Y, and Z on one line because a 
comma follows the last item in the line PRINT X, Y. 
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Example 


INPUT X,Y,Z 
PRINT X,Y, 
PRINT Z 

END 


Output 


? 5,10,15 [RET] 
5 10 15 


The following example shows PRINT statements using a comma, a 
semicolon, and no formatting character after the last print item. 


Example 


'No comma after I%, so each element 
!Prints on its own line 

! 

PRINT I% FOR I% = 1% TO 10% 

PRINT 


'A comma follows J%, so each 
‘element prints in a separate zone 
! 

PRINT J%, FOR J% = 1% TO 10% 
PRINT 


! 
!A semicolon follows K%, so print 
‘elements are packed together 

! 

PRINT K%; FOR K% = 1% TO 10% 

END 


oO 
& 
= 
Ss 
¢ 
= 


FPOWON OCP WH 


0 


1 2 3 4 5 
6 7 8 9 10 
123 45 6 7 8 9 10 
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Commas and semicolons also let you control the placement of string 
output: 

Example 

PRINT "first zone", ,"third zone", ,"fifth zone" 

END 

Output 


first zone third zone fifth zone 


The extra comma between strings causes VAX BASIC to skip another print 
zone. In the following example, the first string is longer than the print 
zone. When the two strings are printed, the second string begins in the 
third print zone because that is the next available print zone after the first 
string is printed. 


Example 


PRINT "abcdefghijklmnopqrstuvwxyz" ,"foo" 
PRINT “first zone","second zone","third zone" 


Output 
abcdefghijklmnopqrstuvwxyz foo 
first zone second zone third zone 


7.2.2 Output Format for Numbers and Strings 


VAX BASIC prints strings exactly as you type them, with no leading or 
trailing spaces. It does not print quotation marks unless they are delimited 
by another matching pair. 


Example 


PRINT 'PRINTING "QUOTATION" MARKS' 
END 


Output 
PRINTING "QUOTATION" MARKS 
VAX BASIC follows these rules for printing numbers: 


e When you print numeric fields, VAX BASIC precedes each number 
with a space or a minus sign and follows it with a space. 
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e VAX BASIC does not print trailing zeros to the right of the decimal 
point. If all digits to the right of the decimal point are zeros, VAX 
BASIC omits the decimal point as well. 


¢ When you print LONG integers, VAX BASIC prints up to 10 significant 
digits. 
¢ When you print DECIMAL values, VAX BASIC prints up to 31 digits. 


VAX BASIC follows these rules for printing floating-point numbers: 


e Ifa floating-point number can be represented exactly by six decimal 
digits (or fewer) and, optionally, a decimal point, VAX BASIC prints it 
that way. 


e When you print a floating-point number whose integer portion is six 
decimal digits or less (for example, 1234.567), VAX BASIC rounds the 
number to six digits (1234.57). If the integer portion of the number is 
seven decimal digits or larger, VAX BASIC rounds the number to six 
digits and prints it in E format. See the VAX BASIC Reference Manual 
for more information about E format. 


e When you print a floating-point number with magnitude between 0.1 
and 1, VAX BASIC rounds it to six digits. When you print a floating- 
point number with more than six digits, and with magnitude smaller 
than 0.1, VAX BASIC rounds it to six digits and prints it in E format. 


The PRINT statement displays only up to six digits of precision for 
floating-point numbers. This corresponds to the precision of the SINGLE 
data type. To display the extra digits in DOUBLE, GFLOAT and HFLOAT 
numbers, you must use the PRINT USING statement. See Chapter 16 for 
more information on PRINT USING. 


The following example shows how VAX BASIC prints various numbers 
with single precision: 
Example 


FOR I = 1 TO 20 
PRINT 2°(-I),1I,2°1 


NEXT I 

END 

Output 
5 4 2 
.25 2 4 
.125 3 8 
.0625 4 16 
.03125 5 32 
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.015625 6 64 

. 78125E-02 7 128 

. 390625E-02 8 256 

. 195313E-02 9 512 
-976563E-03 10 1024 
.488281E-03 11 2048 
.244141E-03 12 4096 

. 12207E-03 13 8192 
-610352E-04 14 16384 
.305176E-04 15 32768 
. 152588E-04 16 65536 
- 767939E-05 17 131072 
.38147E-05 18 262144 
.190735E-05 19 524288 
. 953674E-06 20 . 104858E+07 


7.3 Terminal-Format Files 


Terminal-format files let you perform simple I/O to disk files. The records 
in a terminal-format file must be accessed sequentially. That is, you must 
access the records in the file one by one, from the first to the last. You can 


add new records only at the end of the file. 


Just as the INPUT, LINPUT, and INPUT LINE statements receive in- 
formation from a terminal, the INPUT #, LINPUT #, and INPUT LINE 
# statements receive information from a terminal-format file. And, as 
the PRINT statement sends information to the terminal, the PRINT # 


statement sends information to a terminal-format file. 


Terminal-format files are very useful for creating files to be printed on a 
line printer, or for supplying a program with moderate amounts of input. 
However, if you want to use the same file for both input and output, you 
should not use terminal-format files. Instead, use sequential, relative, or 


indexed files. For more information, see Chapter 15. 


Note that you do not have to use a program to create a terminal-format 
file. You can use a text editor to create a file and insert data, then use a 


VAX BASIC program to open the file and retrieve the data. 
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7.3.1 Opening and Closing a Terminal-Format File 


You use the OPEN statement to create a file, or to gain access to an 
existing file. If you do not specify either FOR INPUT or FOR OUTPUT in 
the OPEN statement, VAX BASIC tries to open an existing file. If the file 
does not exist, VAX BASIC creates a new one. 


The channel specification lets you associate a number with the file for as 
long as the file is open. All I/O operations to or from the file use this 
number. 


When you are finished accessing a file, you close it with the CLOSE 
statement. 


7.3.2 Writing Records to a Terminal-Format File 


The following example receives information from a terminal, then writes 
the information to a terminal-format file as a report: 


Example 


PRINT "This program creates a daily sales report file named SALES.DAT" 
OPEN "SALES.DAT" FOR OUTPUT AS FILE #4% 
PRINT #4%, "Salesperson","Sales Area","Items Sold" 
PRINT #4% 
INPUT “How many salespersons for today's report"; sales_persons%, 
FOR I% = 1% TO sales_persons% 
INPUT "Salesperson's name"; s_name$ 
INPUT "Sales area"; area$ 
INPUT "Number of items sold"; items_sold%, 
PRINT #4%, s_name$, area$, items_sold%, 
NEXT 1% 
CLOSE #47, 
END 


Output 


This program creates a daily sales report file named SALES .DAT 
How many salespersons for today's report? 3 

Salesperson's name? JONES 

Sales area? NJ 

Items sold? 5 
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Salesperson's name? SMITH 
Sales area? NH 

Items sold? 6 
Salesperson's name? BAINES 
Sales area? VT 

Items sold? 8 


This program first prints a header explaining its purpose, then opens a 
terminal-format file on channel 4. After this file is opened, the two PRINT 
# statements place an explanatory header followed by a blank line into 
the file. 


The program then prompts you for the number of salespersons for which 
data is to be entered. The FOR...NEXT loop prompts for the name, sales 
area, and items sold for each salesperson. Note that the FOR...NEXT loop 
executes only as many times as there are salespersons. See Chapter 11 for 
more information about FOR...NEXT loops. 


After the data has been entered for each salesperson, the program writes 
this information to the terminal-format file. Because the response to the 
first question was 3, the FOR...NEXT loop executes three times. 


After the last item has been printed to the file, the program closes the file 
and ends. When you display the file with the DCL command TYPE, you 
see that the information is printed under the proper headers. You can also 
print the file on a line printer. Note that the PRINT # statement formats 
the output in print zones as the PRINT statement does. 


Example 

$TYPE SALES.DAT 

Salesman Sales Area Items Sold 
JONES NJ 5 

SMITH NH 8 

BAINES VT 8 
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Chapter 8 
Arrays 


An array is a set of data that is ordered in any number of dimensions. 
This chapter describes how to create and use VAX BASIC arrays. 


8.1 Introduction 


A one-dimensional array is called a list or vector. A two-dimensional array 
is called a matrix. VAX BASIC arrays can have up to 32 dimensions, and 
a specific type of VAX BASIC arrays can be redimensioned at run time. In 
addition, you can specify the data type of the values in an array by using 
data type keywords or suffixes. 


The subscript of an element in an array defines that element’s position in 
the array. When you create an array, you specify: 


¢ The number of dimensions that the array contains 
e The range of values for the subscripts in each dimension of the array 


VAX BASIC arrays are zero-based by default; that is, when calculating the 
number of elements in a dimension, you count from zero to the number of 
elements specified. For example, an array with an upper bound of 10 and 
no specified lower bound, has 11 elements: 0 through 10, inclusive. The 
array My_array(3,3) has 16 elements: 0 through 3 in each dimension, or 
4. 
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VAX BASIC also lets you specify a lower bound for any or all dimensions 
in an array unless the array is a virtual array. By specifying lower and 
upper bounds for arrays, you can make your array subscripts meaningful. 
For example, the following array contains sales information for the years 
1980 to 1985: 


DECLARE REAL Sales_data(1980 TO 1985) 


To refer to an element in the array Sales_data, you need only specify the 
year you are interested in. For example, to print the information for the 
year 1982, you would type: 


PRINT Sales_data(1982) 


You can create arrays either implicitly or explicitly. You implicitly create 
arrays having any number of dimensions by referencing an element of the 
array. If you implicitly create an array, VAX BASIC sets the upper bound 
to 10 and the lower bound to zero. Therefore, any array that you create 
implicitly contains 11 elements in each dimension. 


The following example refers to the array Student_grades. If the array has 
not been previously declared, VAX BASIC will create a one-dimensional 
array with that name. The array will contain 11 elements. 


Student_grades(8) = "B" 


You create arrays explicitly by declaring them in a DIM, DECLARE, 
COMMON, or MAP statement, or record declaration. Note that if you 
want to specify lower bounds for your array subscripts, you must declare 
the array explicitly. 


When you declare an array explicitly, the value that you give for the upper 
bound determines the maximum subscript value in that dimension. If you 
specify a lower bound, then that is the minimum subscript value in that 
dimension. If you do not specify a lower bound, VAX BASIC sets the 
lower bound in that dimension to zero. You can specify bounds as either 
positive or negative values. However, the lower bound of each dimension 
must always be less than or equal to the upper bound for that dimension. 


You can use MAT statements to create and manipulate arrays. However, 
MAT statements are valid only on arrays of one or two dimensions. In 
addition, the lower bounds of all dimensions in an array referenced in a 
MAT statement must be zero. 


8.2 Creating Arrays Explicitly 


You can create arrays explicitly with four VAX BASIC statements: 
DECLARE, DIMENSION, COMMON, and MAP. 


In addition, you can declare arrays as components of a record data type. 
See Chapter 10 for more information on records. 


Normally, you use the DECLARE statement to create arrays. However, in 
certain cases, you may want to create the array with another VAX BASIC 
statement: 


e You use the DIM statement to create virtual arrays and arrays that can 
be redimensioned at run time. 


e You use the COMMON statement to create arrays that can be shared 
among program modules or to create arrays of fixed-length strings. 


e You use the MAP statement to create an array and associate it with a 
record buffer, or to overlay the storage for an array, thus accessing the 
same storage in different ways. 


When you create an array, the bounds you specify determine the ar- 
ray’s size. The maximum value allowed for a bound can be as large as 
2147483467; however, this number is actually limited by the amount of 
virtual storage available to you. Very large arrays and arrays with many 
dimensions can cause fatal errors at both compile time and run time. 


The following restrictions apply to arrays: 
e When referencing an array, you must use the same number of sub- 
scripts as was specified in the DIM statement. 


e You can use identical names for a simple variable and an array; for 
example, A% and A%(5,5). However, this is not a recommended 
programming practice. If you use identical names for arrays with a 
different number of subscripts, for example, A(5), and A(10,10), VAX 
BASIC prints the error “Inconsistent subscript usage” at compile time. 


e If subscript checking is enabled, VAX BASIC signals the error 
“Subscript out of range” (ERR=55) if you reference an array element 
whose subscripts are one of the following: 


— Greater than the current upper bound of the array 
— Less than the current lower bound of the array 
— Less than zero where no lower bound was specified 
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8.2.1 Creating Arrays with the DECLARE Statement 


The DECLARE statement creates and names variables and arrays. All 
elements of arrays created with the DECLARE statement are initialized to 
zero or the null string. The following statement creates a longword integer 
array with 11 elements. 


DECLARE LONG FIRST_ARRAY(1970 TO 1980) 


Note that the STRING data type with the DECLARE statement causes the 
creation of an array of dynamic strings. To create an array of fixed-length 
strings, declare the array in a COMMON or MAP statement or as part of a 
RECORD structure. 


8.2.2 Creating Arrays with the DIM Statement 
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The DIM statement creates and names one or more arrays. You should 
use the DIM statement to create an array only when you want to 


e Redimension the array at run time 
e Create a virtual array 


When creating arrays with DIM, you specify the data type of the array 
elements with a data type keyword, a special suffix on the array name, 
or both. The array name can be any valid variable name. If you do not 
supply a data type keyword, the data type is determined by the suffix of 
the array name: 


e If the array name ends in a dollar sign, the array stores string data. 
e If the array name ends in a percent sign, the array stores integer data. 


e If the array name does not end in either a percent sign or a dollar 
sign, the array stores data of the default type. The default type is 
single-precision floating-point unless you change the default. See 
Chapter 6 for more information on default data types. 


Even if the DIM statement contains a data type keyword, the array name 
can still end in the appropriate data type suffix. This makes the data type 
of the array immediately obvious. 


The DIM statement can be either executable or declarative. If the specified 
bounds are constants, the DIM statement is declarative. This means that 
the storage is allocated at compile time, and the array cannot appear in 
any other DIM statement. 


However, if any of the specified bounds are variables (simple or sub- 
scripted), the DIM statement is executable. This means that the storage 
for the array is allocated at run time, and the array can be redimensioned 
with a DIM statement any number of times. 


NOTE 


In the DIM statement, bounds can be either constants or 
variables (simple or subscripted), but not expressions. 


When an array is redimensioned with the executable DIM statement, the 

array can become larger or smaller than it was. However, redimensioning 
an array in this way causes it to be reinitialized, and all data in the array 

is lost. 


In contrast, MAT statements let you redimension an array to be the same 
size or smaller than it was. However, MAT statements redimension arrays 
only when assigning values or performing matrix I/O; therefore, the fact 
that MAT reinitializes the array does not matter. See Section 8.6 for more 
information on MAT statements. 


8.2.2.1 Declarative DIM Statements 


Declarative DIM statements are those with integer constants as bounds. 
The percent sign is optional for bounds; however, VAX BASIC signals 
the error “Integer constant required” if a constant bound contains a 
decimal point. The following statement creates a 101-element virtual 
array containing string data. The elements of this array can each have a 
maximum length of 256 characters. 


DIM #1%, STRING VIRT_ARRAY(100) = 256% 
The following restrictions apply to the use of declarative DIM statements: 


e A declarative DIM statement must lexically precede any reference to 
the array it dimensions. 
e¢ The lower bounds of all virtual array dimensions must be zero. 


¢ You must open a VIRTUAL file on the specified channel before you 
can access elements of the virtual array. 
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8.2.2.2 Executable DIM Statements 
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Executable DIM statements are those with at least one variable bound. 
Bounds can be constants or simple variables, but at least one bound 
must be a variable. Executable DIM statements let you redimension an 
array at run time. The bounds of the array can become larger or smaller, 
but the number of dimensions cannot change. For example, you cannot 
redimension a four-dimensional array to be five-dimensional. 


The executable DIM statement cannot be used on arrays in COMMON, 
MAP, DECLARE or declarative DIM statements, nor on virtual arrays or 
arrays received as formal parameters. 


Whenever an executable DIM statement executes, it reinitializes the array. 
If you change the values of an executable DIM statement, the initial values 
are reset each time the DIM statement is executed. 


In the following example, the second DIM statement reinitializes the 
array real_array; therefore, real_array(1) equals zero in the second PRINT 
statement. 


Example 
X% = 10% 
Y% = 20% 


DIM real_array(X%) 
real_array(1%) = 100 
PRINT real_array(1%) 
DIM real_array(Y%) 
PRINT real_array (1%) 
END 


Output 


100 
0 


You cannot reference an array named in an executable DIM statement 
until after the DIM statement executes. If you reference an array element 
declared in an executable DIM statement whose subscripts are larger than 
the bounds specified in the last execution of the DIM statement, VAX 
BASIC signals the run-time error “Subscript out of range” (ERR = 55), 
provided subscript checking is enabled. 


8.2.3 Creating Arrays with the COMMON Statement 


You should create arrays with the COMMON statement when you 
need an array of fixed-length strings, or when you want to share an 
array among program modules. Program modules can share arrays in 
COMMON statements by defining a common block with the same name. 


The COMMON statements in the following programs create a 100-element 
array of fixed-length strings, each element 10 characters long. Because the 
main program and subprograms use the same common name, the storage 

for these arrays is overlaid when the programs are linked. Therefore, both 
programs can read and write data to the array. 


Example 


!'Main Program 
COMMON (ABC) STRING access_list(1 TO 100) = 10 


! Subprogram 
SUB SUB1 
COMMON (ABC) STRING new_list(1 TO 100) = 10 


8.2.4 Creating Arrays with the MAP Statement 


You should create arrays with the MAP statement only when you want 
the array to be part of a record buffer, or when you want to overlay the 
storage containing the array. Note that string arrays in maps are always 
fixed-length. 


You associate the array with a record buffer by naming the map in the 
MAP clause of the OPEN statement. 


In the following example, the MAP statement creates two arrays: an 
11-element fixed-length string array named team and a 33-element array 
of WORD integers named bowling_scores. Because the OPEN statement 
specifies MAP ABC, the storage for these arrays is used as the record 
buffer for the open file. 


MAP (ABC) STRING team(10) = 20, WORD bowling_scores(0 TO 32) 
OPEN "BOWLING.DAT" AS FILE #1%, SEQUENTIAL VARIABLE, MAP ABC 
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8.3 Determining the Bounds of an Array 


VAX BASIC provides two built-in functions, LEOUND and UBOUND, that 
allow you to determine the lower and upper bounds, respectively, for any 
dimension in an array. 


The following example sets up four variables that contain the lower and 
upper bounds of both dimensions of the array Sales_data. These variables 
represent the years and months for which there is sales data available. 
The two FOR...NEXT loops print all the sales information in the array, 
starting with the first year and month, and ending with the last year and 
month. 


Example 
DECLARE Sales_data(1900 TO 1985, 1 TO 12) 


Month_start% = LBOUND (Sales_data, 2) 
Year_start% = LBOUND (Sales_data, 1) 
Month_end% = UBOUND (Sales_data, 2) 
Year_end% = UBOUND (Sales_data, 1) 
FOR Year% = Year_start% TO Year_end% 


FOR Month% = Month_start% TO Month_end% 
PRINT Sales_data(Year%, Month%) 
NEXT Month% 


NEXT Year% 
Note that you cannot implicitly declare arrays with the LBOUND and 


UBOUND functions. These functions can be used only with arrays that 
have been previously declared. 


8.4 Creating Arrays Implicitly 
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There are two ways to create arrays implicitly: 


e By referencing an element of an array that has not been explicitly 
declared 


e By using MAT statements 


When VAX BASIC first creates an implicit array, the lower bound is zero 
and the upper bound is 10. An array created by referencing an element 
can have up to 32 dimensions in VAX BASIC. An array created with a 
MAT statement can have only one or two dimensions. 


NOTE 


The ability to create arrays implicitly exists for compatibility 
with previous implementations of VAX BASIC. However, it 

is better programming practice to declare all arrays explicitly 
before using them. 


If you reference an element of an array that has not been explicitly 
declared, VAX BASIC creates a new array with the name you specify. 
Arrays created by reference have default subscripts of (0 TO 10), (0 TO 
10, 0 TO 10), (0 TO 10, 0 TO 10, 0 TO 10) and so on, depending on the 
number of dimensions specified in the array reference. For example, the 
following program implicitly creates three arrays and assigns a value to 
one element of each. 


Example 


LET A(5,5,5) = 3.14159 

LET B%(3) = 33 

LET C$(2,2) = "Russell Scott" 
END 


The first LET statement creates an 11 by 11 by 11 array that stores 
floating-point numbers and assigns the value 3.14159 to element (5,5,5). 
The second LET statement creates an 11-element list that stores integers 
and assigns the value 33 to element (3) and the third LET statement 
creates an 11 by 11 string array and assigns the value “Russell Scott” to 
element (2,2). 


When you create an implicit numeric array by referring to an element, 
VAX BASIC initializes all elements (except the one assigned a value) to 
zero. For implicit string arrays, VAX BASIC initializes all elements (except 
the one assigned a value) to a null string. When you implicitly create an 
array, you cannot specify a subscript greater than 10. An attempt to do so 
causes VAX BASIC to signal “Subscript out of range” (ERR = 55), provided 
that subscript checking is enabled. 


Note that you cannot create an array implicitly, then redimension the 
array with an executable DIM statement. The DIM statement must execute 
before any reference to the array. 


An array name cannot appear in a declarative statement after the array 
has been implicitly declared by a reference. The following DECLARE 
statement is therefore illegal and causes VAX BASIC to signal the compile- 
time error “illegal multiple definition of name NEW_ARRAY’. 


new_array (5,5,5) = 1 
DECLARE LONG new_array (15,10,5) 
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8.5 Assigning and Displaying Array Values 


You can assign values to array elements from within your program, from 
an external source, such as terminal input or from files, or with MAT 
statements. 


You can write data from an array with the following statements: 


e LET 
e PRINT 


The following sections tell you how to perform input and output opera- 
tions on VAX BASIC arrays. 


8.5.1 Assigning Values with the LET Statement 
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The LET statement assigns values to individual array elements. 


Example 


DIM voucher_num% (100) 
LET voucher_num%(20) = 3253% 


END 


You can also assign values to a portion of an array with the LET statement 
and a FOR...NEXT loop. In the following example, the FOR...NEXT loop 
assigns zero to array elements (1,5) through (1,10), (2,5) through (2,10), 
and (3,5) through (3,10). 


Example 
DIM po_number% (100, 100) 


FOR I% = 1% TO 3% 
FOR J% = 5% TO 10% 
LET po_number%(1I%,J%) = 0% 
NEXT J% 
NEXT I% 


END 


8.5.2 Listing Array Elements with the PRINT Statement 
You print individual array elements by naming those elements in the 
PRINT statement. For example: 
PRINT parts_list$(35%) 


With a FOR...NEXT loop, you can print all or part of an array: 


Example 


DIM capture_ratio(10,10) 


FOR Y%Z = 7% TO 10% 
FOR X% = 7% TO 10% 
PRINT capture_ratio(X%,Y%) 
NEXT X% 
NEXT Y% 


8.6 Using MAT Statements 


MAT statements let you assign values to or display entire arrays with a 
single statement. They also: 

e Implicitly create arrays 

e Assign names to arrays 

e Specify array dimensions 

e Redimension existing arrays (to equal or smaller sizes) 
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e Assign element values 
e Print the contents of arrays 
¢ Perform matrix arithmetic 


MAT statements are valid only on arrays of one or two dimensions. 
When MAT statements execute, they use row and column zero to store 
intermediate calculations. This means that MAT statements can overwrite 
data stored in row and column zero of your arrays, and you should not 
depend on data in these elements if your program uses MAT statements. 


NOTE 


MAT statements cannot be used with arrays that have lower 
bounds other than zero. An attempt to specify a lower bound 
other than zero for an array in a MAT statement results in a 
compile-time error. 


Note that the MAT statements discussed in this section are not related to 
the MAT GRAPH and MAT PLOT graphics statements. For more informa- 
tion on these statements, see Programming with VAX BASIC Graphics. 


The default subscripts for arrays created implicitly with MAT statements 
are (10) or (10,10). The default is two dimensions. This means that if you 
create an array with a MAT statement and do not specify any subscripts, 
VAX BASIC creates a two-dimensional, 11 by 11 array. If you specify 

a single subscript, VAX BASIC creates a one-dimensional array with 11 
elements. 


Table 8-1 lists MAT statements and explains their functions. 


Table 8-1: MAT Statements 
Statement Function 


MAT Assigns values of zero, 1, or a null string to array 
elements. Also copies the values of one array to another 
and performs matrix arithmetic. 


MAT INPUT [#] Assigns values to array elements from your terminal or 
a terminal-format file. 


MAT LINPUT [#] Assigns string values to string array elements from your 
terminal or from a terminal-format file. 


MAT PRINT [#] Displays the contents of an array on your terminal, or 
writes array element values to a terminal-format file. 


MAT READ Assigns DATA statement values to array elements. 


In the following example, the first MAT statement creates the string array 
z—array$ with eight rows and eight columns and assigns a null string to 
all elements. The second MAT statement redimensions the array to six 
rows and six columns. The third MAT statement adds the values in each 
corresponding element of arrays B and C and stores the values in the 
corresponding elements of array A. 


Example 


MAT z_array$ = NUL$(7,7) 
MAT z_array$ = NUL$(5,5) 
MAT A=B+C 

END 


8.6.1 The MAT Statement 


The MAT statement can create an array and optionally assign values to all 
elements in that array. By specifying one of the MAT statement keywords, 
you can initialize arrays in one of four ways. Table 8-2 lists the MAT 
statement keywords and their functions. 
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Table 8-2: MAT Statement Keywords 


MAT Keyword 
ZER 
CON 


IDN 


NUL$ 


Function 
Sets the value of all elements in a numeric array to zero. 


Sets the value of all elements in a numeric array to 1, 
except those in row and column zero. 


Sets the array to the identity matrix, that is, it sets the 
value of all elements in real or integer arrays to zero, 
except for those elements on the diagonal from element 
(1,1) to element (n,n), where n is the largest subscript 
in the array. The elements on the diagonal are set to 1. 
IDN applies to square arrays only. 


Sets the value of all elements in a string array to the 
null string, except those in row and column zero. 


The array name can specify an existing array. MAT statements do not 
assign values to row and column zero. 


Note that the MAT statement does not require subscripts. In the case of 


existing arrays: 


¢ If you do not specify subscripts, VAX BASIC does not change the 


current subscripts. 


e If you specify subscripts, VAX BASIC redimensions the array to the 
specified subscripts. When redimensioning arrays with MAT, you 
cannot increase the total number of array elements (including those in 
row and column zero). 


When you are creating arrays with MAT: 


e If you do not supply subscripts, VAX BASIC assigns two subscripts, 
each with a value of 10. 


e If you specify subscripts, they define the dimensions of the array being 
implicitly created. Subscript values cannot exceed 10. 


Example 
DIM A(10,10), B(15), €(20,20) 


MAT A = ZER !Sets all elements of A to 0 
MAT B = CON(10) !Sets elements of B to 1; redimensions B 
MAT C = IDN(10,10) !Redimensions C to 10x10 identity matrix 
PRINT "ARRAY A:" 

MAT PRINT A; 

PRINT 

PRINT "ARRAY B:" 

MAT PRINT B; 

PRINT 

PRINT "ARRAY C:" 

MAT PRINT C; 

Output 

ARRAY A: 
0000000000 
000000000 0 
000000000 0 
000000000 0 
0000000000 
000000000 0 
000000000 0 
000000000 0 
000000000 0 
0000000000 
ARRAY B 

1 11%41%1%1d141éd4:1éd41é«41 
ARRAY C: 
100000000 0 
0100000040 0 
0010000000 
0003100000 (0 
000010000 «0 
000001000 0 
000000100 0 
000000010 «0 
0000000010 
0000000001 





8.6.2 The MAT READ Statement 


The MAT READ statement assigns values from DATA statements to array 
elements. Subscripts define either the dimensions of the array being 
created or the new dimensions of an existing array; subscripts are optional 
in MAT READ statements. 
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If you do not provide enough data in DATA statements to fill the specified 
array, VAX BASIC leaves the remaining array elements unchanged. If 
you provide more data values than there are array elements, VAX BASIC 
assigns enough values to fill the array and leaves the DATA pointer at the 
next value. 


In the following example, VAX BASIC fills matrix B with the first four 
DATA items, fills matrix C with the next four DATA values, and leaves the 
DATA pointer at the ninth value in the DATA list. 


Example 


MAT READ B(2,2) 
MAT READ C(2,2) 
PRINT 

PRINT "MATRIX B" 
PRINT 

PRINT 

MAT PRINT B; 


PRINT 

PRINT "MATRIX C" 

PRINT 

PRINT 

MAT PRINT C; 

DATA 1,2,3,4,5,6,7,8,9,10 
END 


Output 


MATRIX B 


1 2 
3 4 


MATRIX C 


5 6 
7 8 


8.6.3 The MAT INPUT [#] Statement 
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The MAT INPUT statement assigns values from your terminal to array 
elements. The MAT INPUT # statement reads data from a terminal-format 
file and writes it to an array. The optional subscripts in a MAT INPUT 
statement define either the dimensions of the array being created implicitly 
or the new dimensions of an existing array. If you are implicitly creating 
the array, the value of a subscript cannot exceed 10. 


The MAT INPUT statement requests data from your terminal, as does 
the INPUT statement; it prints a question mark (?) prompt that you can 
disable with the SET NO PROMPT statement and then enable with the 
SET PROMPT statement. However, you cannot include a string prompt 
with the MAT INPUT statement. 


When you enter a series of values separated by commas, VAX BASIC 
enters the values you supply into successive array elements by row, 
starting with element (1,1) and filling row 1 before starting row 2. If you 
provide fewer data items than there are elements, the remaining elements 
are unchanged. If you provide more items than there are elements, VAX 
BASIC ignores the excess. 


The MAT INPUT # statement takes values from an open file and assigns 
them to the matrix elements by rows, starting with element (1,1). It fills 
the elements in row 1 before starting row 2. The file can have one or 
more values in each record; however, multiple values must be separated 
with commas. 


In the following example, the open file on channel 3 contains the fol- 
lowing data: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13. The MAT INPUT # 
statement reads this data and uses it to fill the array A, filling in row 1 
before beginning row 2. The MAT INPUT B(2,2) statement dimensions 
array B to 9 elements (0 to 2 in each dimension) and provides values for 
all the elements except those in row and column zero. 


Example 

MAT INPUT #3, A 

PRINT 

MAT PRINT A; 

MAT INPUT B(2,2) 

PRINT 

MAT PRINT B; 

Output 
123 45 6789 10 
111213 0000000 
0000000000 
0000000000 
0000000000 
0000000000 
0000000000 
0000000000 
0000000000 
0000000000 
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7 1,2,3,4| RET] 


1 2 
3.4 


Note that the MAT PRINT statement does not print row and column zero. 
For more information on the MAT PRINT statement, see Section 8.6.5. 


The MAT INPUT statement can also redimension an existing array. 


Example 


DIM new_array%,(5,5) 
MAT INPUT new_array%,(2,4) 
MAT PRINT new_array%; 


END 

Output 

? 1,2,3,4,5,6,7,8(RET| 
1234 

5678 


When entering values in response to MAT INPUT, you can enter an 
ampersand as the last character on the line and continue on the next line. 


8.6.4 The MAT LINPUT [#] Statement 
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The MAT LINPUT statement assigns string values to string array elements. 
The MAT LINPUT # statement reads string values from a terminal-format 
file and writes them to a string array. 


The MAT LINPUT statement prompts for individual array elements. It 
fills the array by rows, starting with element (1,1). It assigns the line 
you supply (including commas, semicolons, and quotation marks, but 
excluding the line terminator) to an array element. 


Example 


DIM emp_nam$(5,5) 

MAT LINPUT emp_nam$(2,2) 
PRINT emp_nam$(1,1) 
PRINT emp_nam$(1,2) 
PRINT emp_nam$(2,1) 
PRINT emp_nam$(2,2) 


END 
Output 

? HODGES 

? LAFFERTY 
? ELDON 

? HOPKINS 
HODGES 
LAFFERTY 

ELDON 

HOPKINS 


By specifying the subscripts (2,2), MAT LINPUT redimensions the array 
to four elements and overwrites the old values. VAX BASIC then prompts 
for these elements. 


MAT LINPUT # also excludes line terminators when assigning values to 
string array elements. MAT LINPUT # places the values from the open 
file into the specified array, filling the array by rows, starting with element 
(1,1). If there are more values in the file than there are array elements, 
VAX BASIC ignores the excess. If there are fewer, VAX BASIC assigns a 
null string to the remaining elements. 


The following program reads 50 records from the open disk file and 
assigns them to the array named part_name$. If there are more than 50 
records in the file, VAX BASIC ignores the excess. If there are fewer than 
50 records, then VAX BASIC fills the remaining elements of the array with 
the null string. 


Example 


DIM part_name$(50) 
MAT LINPUT #1%, part_name$ 


8.6.5 The MAT PRINT [#] Statement 


The MAT PRINT statement prints some or all of an array’s elements, 
excluding row and column zero. The MAT PRINT # statement takes 
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values from an array by row, starting with element (1,1), and writes each 
element to a sequential record in the terminal-format file. 


Subscripts are optional in MAT PRINT statements. If you do not specify 
subscripts, MAT PRINT displays the entire array, excluding row and 
column zero. If you specify subscripts, MAT PRINT displays the specified 
subset of the array. In the case of the MAT PRINT # statement, the 
subscripts determine how many array elements are written to the file. The 
MAT PRINT [#] statement does not redimension an existing array. 


If the last character in the MAT PRINT [#] array list is a semicolon, VAX 
BASIC begins each array row on a separate line. Data values on each 
line are packed together with no intermediate spaces. However, if the last 
character in the MAT PRINT [#] arrays list is a comma, VAX BASIC begins 
each array row on a separate line and each data value in a separate print 
zone. 


If there is neither a comma nor a semicolon after the array name, VAX 
BASIC prints each array element on a separate line. In the following 
example, the first MAT PRINT statement does not end in a comma or 
semicolon, so each element is printed on a separate line. The second MAT 
PRINT statement prints the elements twice, the first time starting each 
element in a new print zone, and the second time leaving a space before 
and after each value. The MAT PRINT # statement sends the last two 
lines of output to a terminal-format file. 


Example 


MAT INPUT A(5) 
PRINT 

MAT PRINT A 

PRINT 

MAT PRINT A, A; 
MAT PRINT #3, A, A; 
END 


Output 
75 


aaoamoo°coeoa 


0 0 0 0 


8.6.6 Matrix 1/0 Functions (NUM and NUM2) 


MAT statements do not signal error messages when there are more data 
items than array elements to contain them or when there are fewer data 
items than array elements to contain them. 


VAX BASIC provides two functions that let you determine how much data 
the MAT statements transfer: NUM and NUM2. 


For two-dimensional arrays, the NUM function returns an integer value 
specifying the row number of the last data item transferred, whereas the 
NUM2 function returns an integer value specifying the column number 
of the last data item transferred. For one-dimensional arrays, the NUM 
function returns the number of items entered, whereas the NUM2 function 
returns a zero. 


With these functions, you can determine the number of items transferred 
from a terminal-format file. Note, however, that you cannot use the NUM 
and NUM2 functions to implicitly declare an array. In the following 
example, the terminal-format file EMP.DAT contains the values 1 through 
17, inclusive. When these values are read using the MAT INPUT # 
statement, NUM and NUM2 represent the row and column number, 
respectively, of the last value read: 


Example 


OPEN "EMP.DAT" FOR INPUT AS FILE #3% 
DIM emp_name$(5,5) 

MAT INPUT #3%, emp_name$ 

PRINT NUM, NUM2 

END 


Output 
4 2 


8.7 Matrix Operators 


VAX BASIC provides a special set of MAT statements for array com- 
putations. These statements enable you to add, subtract, and multiply 
matrices, and to assign values to elements. Note that if you specify 
an array without subscripts (for example, MAT A), the default is two 
dimensions. 
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VAX BASIC also provides matrix functions to transpose and invert matri- 
ces, and to find the determinant of a matrix you invert. 


NOTE 


MAT operators do not operate on elements in row or column 
zero. 


8.7.1 Arithmetic Matrix Operations 


8.7.1.1 


MAT operators perform matrix assignment, addition, subtraction, and 
multiplication. 


All of these operations use the keyword MAT, followed by an expression. 
If the array has not been previously dimensioned, these operations create 
an array. The created output array’s dimensions depend on the operation 
performed, but must be (10,10) or smaller. 


NOTE 


You can use the MAT operators on arrays larger than (10,10) if 
the input and output arrays are explicitly created or received as 
a formal parameter. 


Assignment 


You can assign all values in one array to another array with the MAT 
statement. In the following example, each element of new_array is set to 
the corresponding element in old_array. The dimensions of new_array are 
also redimensioned to the dimensions of old_array. 


MAT new_array = old_array 


8.7.1.2 Addition and Subtraction 
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You can add the elements of two arrays. In the following statement, 
the two input lists, first_list% and second_list%, must have identical 
dimensions. The elements of the new list, sum_list%, equal the sum of 
the corresponding elements in the input lists. 


MAT sum_list% = first_list% + second_list% 


You can also subtract the elements of two arrays. The following program 
subtracts one array from another. 


Example 


DIM first_array (30,30) 
DIM second_array (30,30) 
DIM difference_array (30,30) 


MAT difference_array = first_array - second_array 


Each element of difference_array is the arithmetic difference of the corre- 
sponding elements of the input arrays. 


8.7.1.3 Multiplication 


You can multiply the elements of two arrays, provided that the number of 
columns in the first array equals the number of rows in the second array. 
The resulting array contains the dot product of the two input arrays. 


Example 


DIM A(2,2), B(2,2), C(2,2) 
A(1,1) = 
A(1,2) 
A(2,1) 
A(2,2) 
B(1,1) 
B(1,2) = 
B(2,1) 
B(2,2) 
MAT C=A*B 
MAT PRINT C 


tut ut ow th of 
ANOoahWwNnNe 


Output 


19 
22 
43 
50 


You can also multiply a matrix by a scalar quantity. VAX BASIC multiplies 
each element of the input array by the scalar quantity you supply. The 
output array has the same dimensions as the input array. Enclose the 
scalar quantity in parentheses. The following example multiplies the 
elements of inch_array by the inch-to-centimeter conversion factor and 
places these values in cm_array. 
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Example 


DIM inch_array(5), cm_array(5) 

MAT READ inch_array 

DATA 1,12,36,100,39.37 

MAT cm_array = (2.54) * inch_array 
MAT PRINT cm_array, 

END 


Output 


2.54 30.48 91.44 254 99.9998 


8.7.2 Matrix Functions 


8.7.2.1 
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VAX BASIC provides three matrix functions: 


e TRN 
e INV 
e DET 


With these functions, you can transpose and invert matrices, and find the 
determinant of an inverted matrix. 


The TRN Function 


The TRN function transposes a matrix. When you transpose a matrix, 
VAX BASIC interchanges the array’s dimensions. For example, a matrix 
with n rows and m columns is transposed to a matrix with m rows and 

n columns. The elements in the first row of the input matrix become the 
elements in the first column of the output matrix. You cannot transpose a 
matrix to itself; MAT A = TRN(A) is invalid. 


This example creates a 3 by 5 matrix, transposes it, and prints the results. 


Example 


DIM B(3,5) 

MAT READ B 

MAT A = TRN(B) 

DATA 1,2,3,4,5 
DATA 6,7,8,9,10 
DATA 11,12,13,14,15 
MAT PRINT B; 

MAT PRINT A; 

END 


Output 


123465 
789 10 
1 12 13 14 15 


6 
1 
1 
2 
3 
4 
5 


8.7.2.2 The INV Function 


The INV function inverts a matrix. VAX BASIC can invert a matrix only 
if its subscripts are identical and it can be reduced to the identity matrix 
by elementary row operations. The input matrix multiplied by the output 
matrix (its inverse) always gives the identity matrix as a result. 


Example 


MAT INPUT first_array(3,3) 

MAT PRINT first_array; 

PRINT 

MAT inv_array = INV (first_array) 

MAT PRINT inv_array; 

PRINT 

MAT mult_array = first_array * inv_array 
MAT PRINT mult_array; 
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Output 
? 4,0,0,0,0,2,0,8,0[RET] 


oof 
ooo 
oN Oo 


-26 0 0 


oor 0°90 
oro 
Be OO 


8.7.2.3. The DET Function 


The DET function returns the determinant of a matrix. The DET function 
returns a floating-point number that is the determinant of the last matrix 

inverted. If you use the DET function before inverting a matrix, the value 
of DET is zero. 
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Chapter 9 
Data Definition 


This chapter describes how to define program objects, explicitly assign 
data types to program variables, and allocate and use data storage. 


9.1 Declarative Statements 


You use declarative statements to define objects in a VAX BASIC program. 
Objects can be variables, arrays, constants, and user-defined functions 
within a program module. They can also be routines, variables, and 
constants external to the program module. Declarative statements always 
assign names to the objects declared and usually assign other attributes, 
such as a data type, to them. Declarative statements can also be used to 
define user-defined data types (RECORD statements). See Chapter 10 in 
this manual for more information on the RECORD statement. 


You use declarative statements to assign data types to: 


e Variables 

e = Arrays 

e Named constants 

e Values returned by functions 


By declaring the objects used in your program, you make the program 
much easier to understand, modify, and debug. 
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9.2 Data Types 


9-2 Data Definition 


At its most fundamental level, a data type is a format for information 
storage. All information is stored in the computer as bit patterns (groups 
of ones and zeros). Data types specify how the computer should interpret 
these patterns. 


VAX BASIC programs allow four general data types: integer, floating- 
point, string, and packed decimal. Each data type is suited for a particular 
type of task. For example, integers are useful for numeric computations 
involving whole numbers, strings provide a way to manipulate alphanu- 
meric characters, and packed decimal data is useful for manipulating 
numeric values that require precise representation. 


Within integer and floating-point data types there are further subdivisions. 
For example, integers can be classed as BYTE, WORD, and LONG. 
Choosing one of these integer subdivisions lets you control two things: 


e¢ The amount of storage required for the integer 
e The range of values that the integer can accept 


See Table 9-1 for more information on the range and storage requirements 
of these integer subtypes. 


Similarly, floating-point data can be classed as SINGLE, DOUBLE, 
GFLOAT, and HFLOAT. See Table 9-1 for more information on the 
range and storage requirements of these floating-point subtypes. 


In addition to numeric and string data types, VAX BASIC also provides 

a unique data type called RFA. Variables of the RFA data type require 

six bytes of storage and can contain only a Record File Address. RFA 
variables are used with RMS file I/O; the operations that can be performed 
on them are strictly limited. See the VAX BASIC Reference Manual for 
more information on the RFA data type. Finally, VAX BASIC allows you 
to construct your own forms of data representation using records. 


Traditionally, VAX BASIC programs have had just three data types: 
integer, string, and floating-point. A data type was assigned to a variable 
with a suffix on the variable names; a dollar sign ($) denoted a string 
variable, a percent sign (%) denoted an integer variable, and variable 
names without suffixes denoted floating-point variables. By referencing a 
variable in your program, you would implicitly declare the variable with 
the data type indicated by the suffix character. 


VAX BASIC now lets you explicitly assign data types to variables, param- 
eters, and functions. This feature gives you more control over the storage 
and precision used by your program. You can, however, still use implicit 
data typing in your programs. You can ensure that all program variables 
are explicitly declared by specifying OPTION TYPE = EXPLICIT or by 
using the /TYPE=EXPLICIT qualifier when you compile your programs. 
See Section 9.3 for more information on the OPTION statement. 


Table 9-1 lists the keywords you use to assign data types along with their 
size, range, and precision. 


Table 9-1: VAX BASIC Data Types 


Precision 

Data Type (decimal) 
Keyword Size Range (digits) 
INTEGER 
BYTE 8 bits -~128 to +127 NA 
WORD 16 bits ~32768 to +32767 NA 
LONG 32 bits ~2147483648 to NA 

+2147483647 
REAL 
Aaa =; "marge as) oo "wan ame se, a 
SINGLE 32 bits 29 * 10-8 to 6 

1.7 * 10°8 
DOUBLE 64 bits 29 x 107°8 to 16 

1.7 * 10°8 
GFLOAT 64 bits 56 * 10778 to 15 

90 * 1038 
HFLOAT 128 bits 84 * 107473? to 33 

59 * 104932 
DECIMAL 
TCI AL aA Aa ae Cee ene a Re 
DECIMAL(d;s) 0 to 16 1* 107°! tol * NA 

bytes 10°! 
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Table 9-1 (Cont.): VAX BASIC Data Types 


Precision 

Data Type (decimal) 
Keyword Size Range (digits) 
STRING 
STRING One Max = 65535 NA 

character 

per byte 
RFA 
RFA 6 bytes NA NA 


As shown in the table, there are four data type keywords that specify 
integer data. The data type INTEGER is a general data type because it 
specifies only that a variable contains integer data. The subtypes BYTE, 
WORD, and LONG specify exactly how much storage is allocated to an 
integer variable. If you specify the INTEGER data type, the subtype of 
integer variables depends on the default integer data type in effect when 
the program is compiled. This default is determined by one of two things: 


e The program’s OPTION statement, if present. See Section 9.3 for 
more information on the OPTION statement. 


e¢ The /INTEGER_SIZE qualifier you use to compile the program. 


Similarly, there are five data type keywords that specify floating-point 
data. The data type REAL is a general data type because it specifies 
only that a variable contains floating-point data. The subtypes SINGLE, 
DOUBLE, GFLOAT, and HFLOAT specify exactly how much storage is 
allocated to a floating-point variable. If you specify the data type REAL, 
the subtype of floating-point variables depends on the default floating- 
point subtype in effect when the program is compiled. This default is 
determined by one of two things: 


¢ The OPTION statement, if present 
¢ The /REAL_SIZE qualifier you use to compile the program 


Choosing a numeric subtype always involves a tradeoff between storage 
requirements and range or precision. You can reduce the size of an 
executable image by choosing the smallest numeric subtype that is large 
enough to meet your needs. 


9.3 Setting the Default Data Type and Size 


There are two ways to set the default data type and size for your program: 


e With the OPTION statement 
e With qualifiers: 

— /TYPE_DEFAULT 
/INTEGER_SIZE 
— /REAL_SIZE 
— /DECIMAL_SIZE 


The OPTION statement can override the defaults set with qualifiers. 
For example, the following statement sets the default integer type to be 
LONG. 


OPTION SIZE = INTEGER LONG 
You can have more than one OPTION statement in a program mod- 


ule; however OPTION statements can be preceded only by a SUB, 
FUNCTION, REM, or another OPTION statement. 


Note that the OPTION statement can also specify the following: 


e Integer and packed decimal overflow checking 

¢ Program optimization 

e Rounding or truncation of packed decimal numbers 
¢ Subscript checking 


See the VAX BASIC Reference Manual for more information about the 
OPTION statement. 


The OPTION statement in the following example specifies that all program 
variables must be explicitly typed and that all implicitly typed constants 
are INTEGER. In addition, any variable typed as INTEGER is a LONG 
integer and any variable typed as REAL is a DOUBLE floating-point 


SIZE = REAL DOUBLE 64-bit floating-point 


numbers by default 


number. 
OPTION TYPE = EXPLICIT, ! Variables must be declared & 
CONSTANT TYPE = INTEGER, ! All implicit constants be integers & 
SIZE = INTEGER LONG, ! 32-bit integers by default & 
! 
! 
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You can create variables of other data types by explicitly declaring them 
with the DECLARE, COMMON, or MAP statement. 


9.4 Declaring Variables Explicitly 
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The DECLARE statement explicitly assigns a data type or subtype to a 
variable, function, or constant. 


The subtype you specify overrides any defaults specified in the OPTION 
statement, in the BASIC environment or with the /INTEGER_SIZE, 
/REAL_SIZE, and /DECIMAL_SIZE qualifiers. For example, if you 
compile your program with the /INTEGER_SIZE=WORD qualifier and 
declare an integer variable to be LONG, the variable is LONG rather than 
WORD. In this format of the DECLARE statement, the data type STRING 
specifies a dynamic string variable. 


You can define a variable only once in a program. For example, if a 
variable name appears in a DECLARE statement, it cannot also appear in 
a COMMON or MAP statement. 


You should use unique variable names to avoid confusion and make 
program documentation easier. For example, if you declare variable B 
to be LONG, there cannot also be a floating-point variable B in your 
program. It is possible to have both an INTEGER variable B% and 
an INTEGER variable B in the same program; however, this is poor 
programming practice. 


When you explicitly declare an array, VAX BASIC allows you to specify 
both upper and lower bound values. The value you supply as the upper 
bound determines the maximum subscript value for a given dimension, 

and the value you supply for the lower bound determines the minimum 
subscript value for a given dimension. 


For more information on specifying bounds with the DECLARE statement, 
see the VAX BASIC Reference Manual and Chapter 8 in this manual. 


You can also use the DECLARE statement to assign a data type and value 
to DEF functions and constants. See Section 9.5 for an explanation of 
declaring named constants. 


The following statement declares the DEF function circumference and 
declares a SINGLE parameter for the function: 


DECLARE LONG FUNCTION circumference (SINGLE) 


DECLARE FUNCTION lets you assign a data type to parameters and to 
the value a function returns. DECLARE FUNCTION also lets you name 
the function without using the usual convention (beginning the function 
name with FN and ending the function name with a percent or dollar sign 
suffix). For example: 


Example 
DECLARE STRING FUNCTION concat (STRING, STRING) !Declare the function 


new_string$ = concat(A$, B$) !Invoke the function 
DEF concat (STRING Y, STRING Z) ‘Define the function 
concat = Y + Z 

END DEF 

END 


This format allows only one data type in a single statement. Declaring 
more than one type of function requires a DECLARE statement for each 


type. 


These data typing features give you control over storage allocation. 
Compiling a program with OPTION TYPE = EXPLICIT is particularly 
useful because it causes VAX BASIC to signal an error when an implicit 
variable is encountered. This prevents a typing mistake from being 
interpreted as a new variable. DIGITAL supports implicit variables for 
compatibility with other BASICs and also because they are useful for 
beginning programmers. However, DIGITAL recommends that you use 
explicit declarations for new program development. 


9.5 Declaring Named Constants Explicitly 


Constants are values that do not change during program execution. You 
can declare named constants within a program unit with the DECLARE 
statement. You can also refer to constants outside the program unit with 
the EXTERNAL statement. In addition, VAX BASIC provides notation for 
binary, octal, decimal, and hexadecimal constants. 
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Named constants are useful for the following reasons: 


¢ If a commonly-used constant must be changed, you can make the 
change in a single place. 


e¢ They make the program easier to understand. 


9.5.1 Declaring Constants Within a Program Unit 


The value assigned to a named constant need not be in the allowable 
range of the default data type; however, it must be in the valid range 

of the data type being declared. The following statement declares a 
LONG constant named XYZ and assigns it a value of 1000. In DECLARE 
CONSTANT statements, VAX BASIC signals an overflow error only if the 
value is outside the range of the data type being declared. 


DECLARE LONG CONSTANT XYZ = 1000 


The following example declares a double-precision constant: 


Example 


DECLARE DOUBLE CONSTANT plancks = 6.6237E-27 
INPUT "FREQUENCY"; freq 

PRINT "ENERGY EQUALS"; plancks / freq 

END 


A DECLARE CONSTANT statement allows only one data type. To declare 
constants of different data types, you must use additional DECLARE 
CONSTANT statements. 


9.5.2 Declaring Constants External to the Program Unit 
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To declare constants external to the program unit, use the EXTERNAL 
statement. For example: 


EXTERNAL LONG CONSTANT SS$_NORMAL 


The VAX/VMS Linker automatically supplies the values for constants 
specified in EXTERNAL statements. For more information on using the 
EXTERNAL statement, see the VAX BASIC Reference Manual. 


9.5.3 Declaring a Default Constant Type 


To declare a default constant type, specify a CONSTANT TYPE clause 
with the OPTION statement. This CONSTANT TYPE clause specifies the 
data type for all constants that do not end in a data type suffix or are not 
in explicit literal notation with a data type supplied. For instance, the 
following OPTION statement specifies that all implicitly typed constants 
will be INTEGER. 


OPTION CONSTANT TYPE = INTEGER 


9.6 Operations with Multiple Data Types 


When an expression contains operands of different data types, it is called a 
mixed-mode expression. Before a mixed-mode expression can be evaluated, 
the operands must be converted, or promoted, to a common data type. The 
result of the evaluation may also be converted depending on the data type 
of the variable to which it is assigned. 


When evaluating mixed-mode expressions, VAX BASIC performs promo- 
tions such that no operand loses any range or precision. When assigning 
values to variables, VAX BASIC converts the result of the expression to 
the data type of the variable. If the value of the expression is outside the 
allowable range of the variable’s data type, VAX BASIC signals “Integer 
error or overflow”, “Floating-point error or overflow”, or “DECIMAL error 
or overflow”. 


In general, VAX BASIC promotes operands with different data types to the 
lowest data type that can hold the largest and most precise possible value 
of either operand’s data type. VAX BASIC then performs the operation 

in that data type, and yields a result of that data type. If the result of the 
expression is assigned to a variable, VAX BASIC converts the result to the 
data type of the variable. Table 9-2 lists the resulting data type for all 
combinations except those involving DECIMAL data types. 
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Table 9-2: Result Data Types in VAX BASIC Expressions 










SINGLE DOUBLE GFLOAT HFLOAT 
BYTE WORD LONG SINGLE DOUBLE GFLOAT HFLOAT 
WORD WORD LONG SINGLE DOUBLE GFLOAT HFLOAT 
LONG LONG LONG SINGLE DOUBLE GFLOAT HFLOAT 
SINGLE SINGLE SINGLE SINGLE DOUBLE GFLOAT HFLOAT 
DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE HFLOAT HFLOAT 
GFLOAT GFLOAT GFLOAT GFLOAT HFLOAT GFLOAT HFLOAT 
HFLOAT HFLOAT HFLOAT HFLOAT HFLOAT HFLOAT HFLOAT 









BYTE 
WORD 
LONG 
SINGLE 
DOUBLE 
GFLOAT 
HFLOAT 








For example, if one operand is SINGLE and one operand is DOUBLE, VAX 
BASIC promotes the SINGLE value to DOUBLE, performs the specified 
operation, and returns the result as a DOUBLE value. This promotion 

is necessary because the SINGLE data type has less precision than the 
DOUBLE value, whereas the DOUBLE data type can hold the largest and 
most precise possible SINGLE value. If VAX BASIC did not promote the 
SINGLE value and the operation yielded a more precise result than was 
represented in SINGLE, the value would lose precision. 


With one exception, the resulting data type is the same as that of the 
operand with the higher data type. The exception is when the operands 
are DOUBLE and GFLOAT. When an expression contains a DOUBLE and 
a GFLOAT operand, VAX BASIC promotes both values to HFLOAT, and 
returns an HFLOAT value. This is necessary because a DOUBLE value 

is more precise than a GFLOAT value, but cannot contain the largest 
possible GFLOAT value. Consequently, VAX BASIC promotes these data 
types to a data type that can hold the largest and most precise value of 
either operand. 


VAX BASIC also allows the DECIMAL(d,s) data type. DECIMAL values 
are converted to REAL before exponentiation. For all other operations 
involving a DECIMAL value, the number of digits (d) and the scale 

or position of the decimal point (s) in the result depend on the data 

type of the other operand. If one operand is DECIMAL and the other is 
DECIMAL or INTEGER, the d and s values of the result are determined as 
follows: 


e If both operands are typed DECIMAL, and if both operands have the 
same digit (d) and scale (s) values, no conversions occur and the 
result of the operation has exactly the same d and s values as the 
operands. Note, however, that overflow can occur if the result exceeds 
the range specified by the d value. 
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¢ If both operands are DECIMAL, but have different digit and scale 
values, VAX BASIC always uses the larger number of specified digits 
for the result. 


In the following statements, variable A allows three digits to the left of the 
decimal point and two digits to the right. Variable B allows one digit to 
the left of the decimal point and three digits to the right. 


DECLARE DECIMAL(5,2) A 
DECLARE DECIMAL(4,3) B 


Therefore, the result allows three digits to the left of the decimal point and 
three digits to the right. 


If one operand is typed DECIMAL and one is typed INTEGER, the 
INTEGER value is converted to a DECIMAL(d;s) data type as follows: 


e BYTE is converted to DECIMAL(3,0). 
e WORD is converted to DECIMAL(5,0). 
e LONG is converted to DECIMAL(10,0). 


VAX BASIC then determines the d and s values of the result by evaluating 
the d and s values of the operands as described above. Note that only 
INTEGER data types are converted to the DECIMAL data type. If one 
operand is DECIMAL and one is floating-point, the DECIMAL value is 
converted to a floating-point value. The total number of digits (d) in the 
DECIMAL value determines its new data type: 


Range of d Converted to: 

<=1 through <= 6 SINGLE 

<= 7 through <= 15 DOUBLE 
GFLOAT 
HFLOAT 

= 16 DOUBLE 

<= 17 through <= 31 HFLOAT 


If the value of d is between 7 and 15, the operand is converted to 
DOUBLE if the floating-point operand is DOUBLE, to GFLOAT if the 
floating-point operand is GFLOAT, and to HFLOAT if the floating-point 
operand is HFLOAT. Thus, a DECIMAL(8,5) operand is converted to 
DOUBLE if the other operand is SINGLE or DOUBLE, to GFLOAT if 
the other operand is GFLOAT, and to HFLOAT if the other operand is 
HFLOAT. 
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Figure 9-1 shows a mixed-mode expression, and the data types of the 
intermediate and final results. 


Figure 9-1: Mixed-Mode Expression Results 


WORD + LONG / DECIMAL(6,2) + ( DOUBLE ~« GFLOAT ) 


\/ 


LONG HFLOAT 


DECIMAL(12,2) 


HFLOAT 
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Note that the LONG integer is first converted to DECIMAL(10,0). When 
VAX BASIC performs the division, both operands are converted to 
DECIMAL(12,2). 


You can convert any numeric variable or expression to a specified data 
type with the REAL, INTEGER, and DECIMAL functions. See the VAX 
BASIC Reference Manual for more information on these functions. 


9.7 Allocating Static Storage 


VAX BASIC programs allocate both static and dynamic storage. The size 
of static storage does not change during program execution. Variables 
and arrays appearing in MAP or COMMON statements use static storage. 
Because this storage is static, all string variables appearing in MAP or 
COMMON statements are fixed-length strings. 
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Dynamic storage is allocated when the program executes. Variables and 
arrays declared in the following statements use dynamic storage: 


e DECLARE statements 
e DIMENSION statements 
¢ Implicitly declared variables 


Normally, string variables and arrays declared in this way are dynamic 
strings, and their length can change during program execution. However, 
if you declare or dimension an array of a user-defined data type (a 
RECORD name), then all string variables and arrays are fixed-length 
strings. See Chapter 10 in this manual for more information about the 
RECORD statement. 


MAP and COMMON statements create a named storage area called a 
program section, or PSECT. MAP statements require a map name, but in 
COMMON statements the name is optional. The PSECT name is the same 
as the map or common name. If you do not specify a common name, VAX 
BASIC supplies a default PSECT name of $BLANK. The following sections 
explain how to use static storage. 


9.7.1 The COMMON Statement 


The COMMON statement defines a named area of storage (called a 
PSECT). Any VAX BASIC subprogram can access the values in a common 
by specifying a common with the same name. An item ina COMMON 
statement can be any one of the following: 

e A numeric variable 

e A numeric array 

e A fixed-length string variable 

e An array of fixed-length strings 

e A RECORD instance 

e =A FILL item 


The amount of storage reserved for a variable depends on its data type. 
You can specify a length for string variables and string array elements 
that appear in a COMMON statement. If you do not specify a length, the 
default is 16. The following statement specifies 2 bytes for emp.code, 3 
bytes for wage.code, and 22 bytes for dep.code. 


COMMON (code) STRING emp.code=2, wage.code=3, dep.code=22 
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In a single program module, multiple common areas with the same 
name allocate storage end-to-end in a single PSECT. That is, VAX BASIC 
concatenates all common areas with the same name in the same program 
module, in the order they appear. For example, the following statements 
allocate storage for five LONG integers in a single PSECT named into. 


COMMON (into) LONG call_count, subi_count, sub2_count 

COMMON (into) LONG sub3_count, sub4_count 

When you explicitly declare an array, VAX BASIC allows you to spec- 
ify both upper and lower bound values. The value you supply as the 
upper bound determines the maximum subscript value for a given dimen- 
sion, whereas the value you supply for the lower bound determines the 
minimum subscript value for a given dimension. 


For more information on specifying bounds with the COMMON state- 
ment, see the VAX BASIC Reference Manual and Chapter 8 in this manual. 


9.7.2 The MAP Statement 


The MAP statement, like the COMMON statement, creates a named area 
of static storage. However, if a program module contains multiple maps 

with the same name, the maps are overlaid on the same area of storage, 

rather than being concatenated. 


When used with the MAP clause of the OPEN statement, the storage 
allocated by the MAP statement becomes the record buffer for that file. 
Variables in the MAP statement correspond to fields in the file’s records. 


A map item can be one of the following: 


e A numeric variable 

e <A numeric array 

e A fixed-length string variable 

e An array of fixed-length strings 
e A RECORD instance 

e ~=6A FILL item 


When you explicitly declare an array, VAX BASIC allows you to spec- 
ify both upper and lower bound values. The value you supply as the 
upper bound determines the maximum subscript value for a given dimen- 
sion, whereas the value you supply for the lower bound determines the 
minimum subscript value for a given dimension. 
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For more information on specifying bounds with the MAP statement, see 
the VAX BASIC Reference Manual, and Chapter 8 in this manual. 


9.7.2.1 Single Maps 


You associate a map with a record buffer by referencing the map in the 
OPEN statement. 


The MAP statement must appear before any reference to map variables. 
For example, the following program uses map variables to access fields 
in payroll records. Changes to map variables do not change the actual 
records in the file. To transfer the changed variables to the file, you 
must use the PUT or UPDATE statement. For more information, see 
Chapter 15. 


Example 


WHEN ERROR USE eof_handler 
DECLARE INTEGER CONSTANT EOF = 11 


MAP (PAYROL) STRING emp_name, LONG wage_class, & 
STRING sal_rev_date, SINGLE tax_ytd 


OPEN "payroll.dat" FOR INPUT AS FILE #4% & 
»ORGANIZATION SEQUENTIAL & 
»ACCESS READ & 
»MAP PAYROL 


OPEN "payrol.new" FOR OUTPUT AS FILE #5% 
,ORGANIZATION SEQUENTIAL 
,ACCESS WRITE 
»MAP payrol 


Be & & 


PRINT "PAYROLL VERIFICATION" 


get_loop: 
WHILE 1% = 1% 

GET #4 
PRINT emp_name, wage_class, sal_rev_date, tax_ytd 
PRINT "YOU CAN CHANGE: " 
PRINT "1. EMPLOYEE NAME" 
PRINT "2. WAGE CLASS" 
PRINT "3. REVIEW DATE" 
PRINT "4. TAX YEAR-TO-DATE" 
PRINT "5. DONE" 


read_loop: 
WHILE 1% = 1% 
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INPUT "CHANGES? ANSWER WITH YES OR NO" ; chng$ 
IF chng$ = "NO" THEN ITERATE get_loop 
ELSE INPUT "NUMBER" ;number% 


END IF 


SELECT number’ 
CASE 1 
INPUT "EMPLOYEE NAME"; emp_name 
CASE 2 
INPUT "WAGE CLASS"; wage_class 
CASE 3 
INPUT "REVIEW DATE" ;sal_rev_date 
CASE 4 
INPUT "TAX YEAR-TO-DATE"; tax_ytd 
CASE 5 
EXIT read_loop 
CASE ELSE 
PRINT "Invalid response -- please try again" 
END SELECT 
NEXT 
PUT #5 
NEXT 
END WHEN 


HANDLER eof_handler 
IF ERR = EOF 
THEN 
PRINT "End of file" 
ELSE 
EXIT HANDLER 
END IF 
END HANDLER 
END 


9.7.2.2 Multiple Maps 


When a program contains more than one map with the same name, 
the storage allocated by these MAP statements is overlaid, as shown in 
Figure 9-2. This technique is useful for manipulating strings. 


When you use more than one map to access a record buffer, VAX BASIC 
uses the size of the largest map to determine the size of the record. 
(The RECORDSIZE clause of the OPEN statement can override this 
map-defined record size. For more information, see Chapter 15.) 
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Figure 9-2: Multiple Maps 


NA. 


ME$= 40 BYTES ADDRESS$= 44 BYTES 


—— E> 


FIRST.NAMES$ LAST.NAMES$ STREET. STREET$ CITY$ 
= = NUMBER$ = = 
15 BYTES 25 BYTES = 16 BYTES 23 BYTES 
5 BYTES 
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You can also use multiple maps to interpret numeric data in more than 
one way. The following example creates a map area named barray. The 
first MAP statement allocates 26 bytes of storage in the form of an integer 
BYTE array. The second MAP statement defines this same storage as a 
26-byte string named ABC. When the FOR...NEXT loop executes, it assigns 
values corresponding to the ASCII values for the uppercase letters A 
through Z. 


Example 


MAP (barray) BYTE alphabet (25) 
MAP (barray) STRING ABC = 26 
FOR I% = 0% TO 25% 

alphabet (I) = I% + 65% 
NEXT 1% 
PRINT ABC 
END 


Output 
ABCDEFGHI JKLMNOPQRSTUVWXYZ 


9.7.3 FILL items 


FILL items reserve space in map and common blocks and in record buffers 
accessed by MOVE or REMAP statements. Thus, FILL items mask parts 
of the record buffer and let you skip over fields and reserve space in or 
between data elements. 
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FILL formats are available for all data types. Table 9-3 summarizes the 
FILL formats and their default allocations if no data type is specified. 


Table 9-3: FILL item Formats, Representations, and Default 


Allocations 

FILL Format Representation Bytes Used 

FILL Floating-point 4, 8, or 16 

FILL(n) n floating-point elements 4n, 8n, or 
16n 

FILL% Integer (BYTE, WORD, or LONG) 1, 2, or 4 

FILL%(n) ; n integer elements 1n, 2n, or 
4n 

FILL$ String 16 

FILL$(n) n string elements 16n 

FILL$ = m String m 

FILL$(n) = m n string elements, m bytes each m*n 


NOTE 


In the applicable formats of FILL, n represents a repeat count, 
not an array subscript. FILL(n), for example, represents 7 real 
elements, not n+1. 


You can also use data type keywords with FILL and optionally data type 
suffixes. The data type and storage requirements are those of the last data 
type specified. For example: 


MAP (QED) STRING A, FILL$=24, LONG SSN, FILL%, REAL SAL, FILL(5) 

This MAP statement uses data type keywords to reserve space for 
e A 16-character string variable A. 

¢ Twenty-four bytes of padding. 

e¢ One LONG variable, SSN. 

e Four bytes of padding. 

e One REAL variable, SAL. 


e Space for five floating-point numbers. This requires 10, 20, or 80 bytes 
of padding, depending on the default size for floating-point numbers. 
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You can specify user-defined data types (RECORD names) for FILL items. 
For instance, in the following example, the first line defines a RECORD of 
data type X. The MAP statement contains a fill item of this data type, thus 
reserving space in the buffer for one RECORD of type X. 
RECORD X 

REAL Yi, ¥2(10) 
END RECORD X 
MAP (QED) X FILL 


See Chapter 10 for more information on the RECORD statement. 


9.7.4 Using COMMON and MAP in Subprograms 


The COMMON and MAP statements create a block of storage called a 
PSECT. This common or map storage block is accessible to any subpro- 
gram. A VAX BASIC main program and a subprogram can share such an 
area by referencing the same common or map name. 


For instance, the following example contains common blocks that define 


e A 16-character string field called A by the main program and X by the 


subprogram 

e A 10-character string field called B by the main program and Z by the 
subprogram 

e <A 4-byte integer field called C by the main program and Y by the 
subprogram 


!In a main program 
COMMON (A1) STRING A, B = 10, LONG C 


!In a subprogranm 
COMMON (Ai) STRING X, Z = 10, LONG Y 


If a subprogram defines a common or map area with the same name as 
a common or map area in the main program, it overlays the common or 
map defined in the main program. 


Multiple COMMON statements with the same name behave differently 
depending on whether these statements are in the same program mod- 
ule. If they are in the same program module, then the storage for each 
common area is concatenated. However, if they are in different program 
units, then the common areas overlay the same storage. The following 
COMMON statements are in the same program module; therefore, they 
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are concatenated in a single PSECT. The PSECT contains two 32-byte 


strings. 
COMMON (XYZ) STRING A = 32 
COMMON (XYZ) STRING B = 32 


In contrast, the following COMMON statements are in different program 
modules, and thus overlay the same storage. Therefore, the PSECT 
contains one 32-byte string, called A in the main program and B in the 
subprogram. 


!In the main program 
COMMON (XYZ) STRING A = 32 


!In the subprogram 
COMMON (XYZ) STRING B = 32 


Although you can redefine the storage in a common section when you 
access it from a subprogram, you should generally not do so. Common 
areas should contain exactly the same variables in all program modules. 
To make sure of this, you should use the %INCLUDE directive, as shown 
in the following example: 


Example 


COMMON (SHARE) WORD emp_nun, 
DECIMAL (8,0) salary, 
STRING wage_class = 2 


& & 


!'In the main program 
“INCLUDE "COMMON .BAS" 


!In the subprogram 
%INCLUDE "COMMON .BAS" 


If you use the %INCLUDE directive, you can lessen the chance of a 
typographical error appearing in your program. For more information on 
using the %INCLUDE directive, see Chapter 18. 


If you must redefine the variables in a PSECT, you should use the MAP 
statement or a record with variants for each overlay. When you use the 
MAP statement, use the %INCLUDE directive to create identical maps 
before redefining them, as shown in the following example. The map 
defined in MAP.BAS is included in both program modules as a 40-byte 
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string. This map is redefined in the subprogram, allowing the subprogram 
to access parts of this string. 


Example 
MAP (REDEF) STRING full_name = 40 


'In the main program 
“%INCLUDE "MAP.BAS" 


!In the subprogram 
“%INCLUDE "MAP .BAS" 
MAP (REDEF) STRING first_name=15, MI=1, last_name=24 


9.8 Dynamic Mapping 


Dynamic mapping lets you redefine the position of variables in a static 
storage area. This storage area can be either a map name or a previously 
declared static string variable. Dynamic mapping requires three VAX 
BASIC statements: 


e A declarative statement, such as a MAP statement, allocating a fixed- 
length storage area 


e A MAP DYNAMIC statement, naming the variables whose positions 
can change at run time 


e A REMAP statement, specifying the new positions of the variables 
named in the MAP DYNAMIC statement 


The MAP DYNAMIC statement does not affect the amount of storage 
allocated. The MAP DYNAMIC statement causes VAX BASIC to create 
internal pointers to the variables and array elements. Until your program 
executes the REMAP statement, the storage for each variable and each 
array element named in the MAP DYNAMIC statement starts at the 
beginning of the map storage area. 


The MAP DYNAMIC statement is nonexecutable. With this statement, 
you cannot specify a string length. All string items have a length of zero 
until the program executes a REMAP statement. 
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The REMAP statement specifies the new positions of variables named 

in the MAP DYNAMIC statement. That is, it causes VAX BASIC to 
change the internal pointers to the data. Because the REMAP statement is 
executable, it can redefine the pointer for a variable or array element each 
time the REMAP statement is executed. 


With the MAP DYNAMIC statement, you can specify either a map name 
or a previously declared static string variable. When you specify a map 
name, a MAP statement with the same map name must lexically precede 
the MAP DYNAMIC statement. 


In the following example, the MAP statement creates a storage area and 
names it emp_buffer. The MAP DYNAMIC statement specifies that the 

positions of variables emp_name and emp_address within the map area, 

can be dynamically defined with the REMAP statement. 


Example 


DECLARE LONG CONSTANT emp_fixed_info = 4 +9 + 2 


MAP (emp_buffer) LONG badge, & 
STRING social_sec_num = 9, & 
BYTE name_length, & 
address_length, & 
FILL (60) 
MAP DYNAMIC (emp_buffer) STRING emp_name, & 
emp_address 
WHILE 1% 
GET #1 
REMAP (emp_buffer) STRING FILL = emp_fixed_info, & 
emp_name = name_length, & 
emp_address = address_length 
NEXT 


At the start of program execution, the storage for badge is the first 4 bytes 
of emp_buffer, the storage for social_sec_num is equal to 9 bytes and 
together name_length and address_length are equal to 2 bytes. The FILL 
keyword reserves 60 additional bytes of storage. The MAP DYNAMIC 
statement defines the variables emp_name and emp—address whose posi- 
tions and lengths will change at run time. When executed, the REMAP 
statement defines the FILL area to be equal to emp_fixed_info and defines 
the positions and lengths of emp_name and emp_address. 


When you specify a static string variable, it must be either a variable 
declared in a MAP or COMMON statement or a parameter declared in a 
SUB, FUNCTION, PICTURE or DEF. The actual parameter passed to the 
procedure must be a static string variable defined in a COMMON, MAP, 
or RECORD statement. 
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The following example shows the use of a static string variable as a 
parameter declared in a SUB. The MAP DYNAMIC statement specifies 
the input parameter, input_rec, as the string to be dynamically defined 
with the REMAP statement. In addition, the MAP DYNAMIC statement 
specifies a string array A whose elements will point to positions in input— 
rec after the REMAP statement is executed. The REMAP statement 
defines the length and position of each element contained in array A. The 
FOR...NEXT loop then assigns each element contained in array A into 
array item, the target array. 


Example 


SUB deblock (STRING input_rec, STRING item()) 
MAP DYNAMIC (input_rec) STRING A(1 TO 3) 
REMAP (input_rec) & 


A(1) = 5, & 
A(2) = 3, & 
A(3) = 4 


FOR I = LBOUND(A) TO UBOUND(A) 
item(I) = A(I) 

NEXT I 

END SUB 


Note that dynamic map variables are local to the program module in 
which they reside. Therefore, REMAP only affects how that module views 
the buffer. 


For more information on using the MAP DYNAMIC and REMAP state- 
ments, see the VAX BASIC Reference Manual. 
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Chapter 10 
Creating and Using Data Structures 


A data structure is a collection of data items that can contain elements or 
components of different data types. 


The RECORD statement lets you create your own data structures. You use 
the RECORD statement to create a pattern of a data structure, called the 
RECORD template. Once you have created a template, you use it to declare 
an instance of the RECORD, that is, a RECORD variable. You declare a 
record variable just as you declare a variable of any other type: with 

the DECLARE statement or another declarative statement. A RECORD 
instance is a variable whose structure matches that of the RECORD 
template. 


Remember that the RECORD statement does not create any variables. It 
merely creates a template, or user-defined data type, that you can then use 
to create variables. 


This chapter describes how to create and use data structures. 


10.1 The RECORD Statement 


The RECORD statement names and defines a data structure. Once a 
data structure (or RECORD) has been named and defined, you can use 
that RECORD name anywhere that you can use a VAX BASIC data type 
keyword. You build the data structure using: 

e Variables of any valid VAX BASIC data type 

e RECORD variables of previously defined RECORD data types 


e Any combination of the two 
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The following example creates a RECORD template called Employee. 
Employee is a data structure that contains one LONG integer, one 
10-character string, one 20-character string, and one 11-character string. 


Example 


RECORD Employee 
LONG Emp_number 
STRING First_name = 10 
STRING Last_name = 20 
STRING Soc_sec_number = 11 
END RECORD Employee 


To create instances of this data structure, you use declarative statements. 
For instance, in the following example, the first DECLARE statement 
creates a variable named Emp_rec of data type Employee. The second 
DECLARE statement creates a one-dimensional array, named Emp_array, 
that contains 1001 instances of the Employee data type. 


Example 


DECLARE Employee Emp_rec 
DECLARE Employee Emp_array (1000) 


Any reference to a RECORD component must contain the name of the 
RECORD instance (that is, the name of the declared variable) and the 
name of the elementary RECORD component you are accessing, separated 
by two colons (::). For example, the following program assigns values to 
an instance of the Employee RECORD template: 


Example 
! Record Template 
RECORD Employee 


LONG Emp_number 
STRING First_name = 10 
STRING Last_name = 10 
STRING Soc_sec_number = ii 


END RECORD Employee 

! Declarations 

DECLARE Employee Emp_rec 
DECLARE STRING Social_security 


! Program logic starts here. 
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INPUT ‘Employee number'; Emp_rec: :Emp_number 
INPUT 'First nanme'; Emp_rec: :First_name 
INPUT 'Last name'; Emp_rec: :Last_name 
INPUT ‘Social security'; Social_security 

IF Social_security <> "" 


THEN 

Emp_rec: :Soc_sec_number = Social_security 
END IF 
PRINT 
PRINT "Employee number is: "; Emp_rec: :Emp_number 
PRINT "First name is: "; Emp_rec: :First_name 
PRINT "Last name is: "; Emp_rec: :Last_name 
PRINT "Social security is: "; Emp_rec: :Soc_sec_number 
END 


When you access an array of RECORD instances, the array subscript 
should immediately follow the name of the RECORD variable. The 
following example shows an array of RECORD instances. 


Example 
! Record Template 
RECORD Employee 


LONG Emp_number 

STRING First_name = 10 
STRING Last_name = 10 
STRING Soc_sec_number = i1 


END RECORD 

! Declarations 

DECLARE Employee Emp_array ( 10 ) 
DECLARE INTEGER Index 

DECLARE STRING Social_security 


! Program logic starts here. 


FOR Index = 0 TO 10 


PRINT 

INPUT 'Employee number'; Emp_array (Index) : :Emp_number 
INPUT 'First name'; Emp_array (Index) : :First_name 
INPUT ‘Last name'; Emp_array (Index) : :Last_name 


INPUT ‘Social security’; Social_security 
IF Social_security <> "" 
THEN 
Emp_array (Index) : :Soc_sec_number = Social_security 
END IF 
NEXT Index 


FOR Index = 0 TO 10 
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PRINT 
PRINT "Employee number is: "; Emp_array (Index) : :Emp_number 


PRINT "First name is: "; Emp_array (Index) : :First_name 
PRINT "Last name is: "; Emp_array (Index) : : Last _name 
PRINT "Social security is: "; Emp_array (Index) : :Soc_sec_number 
NEXT Index 

END 


You can have a RECORD that contains an array. When you declare 
arrays, VAX BASIC allows you to specify both lower and upper bounds. 
Example 


RECORD Grade_record 
STRING Student_name = 30 


INTEGER Quiz_scores (1 TO 10) ! Array to hold ten quiz grades. 
END RECORD 
! Declarations 


DECLARE Grade_record Student_grades ( 5 ) 


!The Student_grades array holds information on six students 
!(0 through 5), each of whom has ten quiz grades (1 through 10). 


DECLARE INTEGER I,J 
!Program logic starts here. 
FOR I = 0 TO 5 !This loop executes once for each student. 


PRINT 
INPUT ‘Student name’; Student_grades(I) : :Student_name 


FOR J = 1 T0 10 !This loop executes ten times for each student. 


PRINT 'Score for quiz number'; J 
INPUT Student_grades(I) : :Quiz_scores (J) 


NEXT J 
NEXT I 
FOR I = 0 TO & 


PRINT 
PRINT ‘Student name: '; Student_grades(I): :Student_name 


FOR J = 1 TO 10 


PRINT 'Score for quiz number’; J; ": "; 
PRINT Student_grades(I) : :Quiz_ scores(J) 
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NEXT J 
NEXT I 
END 


Because any reference to a component of a RECORD instance must 
begin with the name of the RECORD instance, RECORD component 
names need not be unique in your program. For example, you can have 
a RECORD component called First_name in any number of different 
RECORD statements. References to this component are unambiguous 
because every RECORD component reference must specify the record 
instance in which it resides. 


10.1.1 Grouping RECORD Components 


A RECORD component can consist of a named group of instances, iden- 
tified with the keyword GROUP. You use GROUP to refer to a collection 
of RECORD components, or to create an array of components that have 
different data types. The GROUP name can be followed by a list of upper 
and lower bounds, which define an array of the GROUP components. 
GROUP is valid only within a RECORD block. 


The declarations between the GROUP statement and the END GROUP 
statement are called a GROUP block. 


For instance, the following example declares a RECORD template of 
data type Yacht. Yacht is made up of two groups: Type—of_yacht and 
Specifications. Each of these groups is composed of elementary RECORD 
components. VAX BASIC also allows groups within other groups. 


Example 
RECORD Yacht 


GROUP Type_of_yacht 
STRING Manufacturer = 10 
STRING Model = 10 

END GROUP Type_of_yacht 


GROUP Specifications 
STRING Rig = 6 
STRING Length_over_all = 3 
DECIMAL(5,0) Displacement 
DECIMAL(2,0) Beam 
DECIMAL(7,2) Price 

END GROUP Specifications 


END RECORD Yacht 
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10.1.2 RECORD Variants 


In some cases, it is useful to have different record components overlay the 
same record field, in much the same way that multiple maps can overlay 
the same storage. Such an overlay is called a RECORD variant. You use 
the keywords VARIANT and CASE to set up RECORD variants. 


The following example creates a RECORD template for any of three kinds 


of boats. 
Example 
RECORD Boat 
STRING Make = 10 
STRING Model = 10 


STRING Type_of_boat = 1 ! This field contains the value S, P, or C. 
! Value S causes the record instance to be 
! interpreted as describing a sailboat, value 
! P as describing a powerboat, and value C as 
! 


! describing a canoe. 


VARIANT 

CASE ! Sailboats 
STRING Rig = 20 

CASE ! Powerboats 


WORD Horsepower 
CASE ! Canoes 


WORD Length 
WORD Weight 


END VARIANT 
END RECORD 
The SELECT...CASE statement makes it easy to access one of several 
possible RECORD variants in a particular RECORD instance. A RECORD 
component outside the overlaid fields usually determines which RECORD 
variant is being used in a particular reference; in this case the determining 


RECORD component is Type—of_boat. You can use this component in the 
SELECT expression. 
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Example 
! Declarations 
DECLARE Boat My_boat 


! Main program logic starts here 


Input_boat_information: 


INPUT 'Make of boat'; My_boat: :Make 

INPUT 'Model'; My_boat: :Model 

PRINT ‘Type of boat (S = Sailboat, P = Powerboat, C = Canoe)'; 
INPUT My_boat: :Type_of_boat 


SELECT My_boat: : Type_of_boat 
CASE "S" 
INPUT 'Sail rig'; My_boat: :Rig 
CASE "Pp" 
INPUT 'Horsepower'; My_boat: :Horsepower 
CASE "C" 


INPUT 'Length'; My_boat: :Length 
INPUT 'Weight'; My_boat: : Weight 


CASE ELSE 
PRINT “Invalid type of boat, please try again." 
END SELECT 


The value of the Type_of_boat component determines the format of the 
variant part of the record. 


The following example is a slightly more complex version of the same 
type of procedure. This program prompts for the RECORD instance 
components in each variant. When the user responds to the “Wage Class” 
prompt, the program branches to one of three case blocks depending on 
the value of Wage_class. 
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Example 
!'Record templates 
RECORD Emp_wage_class 
STRING Emp_name = 30 ! 


STRING Street = 15 
STRING City = 20 
STRING State = 2 
DECIMAL(5,0) Zip 


STRING Wage_class = 1 


VARIANT 
CASE 
GROUP Hourly 


DECIMAL(4,2) Hourly_wage 
SINGLE Regular_pay_ytd 
SINGLE Overtime_pay_ytd 


END GROUP Hourly 
CASE 
GROUP Salaried 


DECIMAL(7,2) Yearly_salary 
SINGLE Pay_ytd 


END GROUP Salaried 
CASE 
GROUP Executive 


DECIMAL(8,2) Yearly_salary 
SINGLE Pay_ytd 
SINGLE Expenses_ytd 


END GROUP Executive 
END VARIANT 
END RECORD 
! Declarations: 
DECLARE Emp_wage_class Emp 
! Main Program logic starts here. 


LINPUT 
LINPUT 


"Name"; Emp: :Emp_name 
"Street"; Emp: :Street 


LINPUT 
INPUT 
LINPUT 


"State"; Emp: :State 
"Zip Code"; Emp: :Zip 
"Wage Class"; Emp: :Wage_class 
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—- 


— o- 


Employee name string. 


These components make up the 
employee address field. 


‘Hourly workers. 


Hourly wage rate. 
Regular pay year-to-date. 
Overtime pay year-to-date. 


Salaried workers. 


Yearly salary. 
Pay year-to-date. 


Executives. 


Yearly salary. 
Pay year-to-date. 
Expenses year-to-date. 


Use LINPUT statements for 
string fields so the entire 
string is assigned to the 
variable. 


SELECT Emp: :Wage_class 


CASE "A" 
INPUT 'Rate';Emp: :Hourly_wage 
INPUT ‘Regular pay' ;Emp: :Regular_pay_ytd 
INPUT ‘Overtime pay' ;Emp: :Overtime_pay_ytd 
CASE "B" 
INPUT 'Salary' ;Emp: :Salaried: :yearly_salary 
INPUT 'Pay YTD';Emp: :Salaried: :pay_ytd 
CASE "C" 
INPUT 'Salary';Emp: :Executive: :yearly_salary 
INPUT 'Pay YTD';Emp: :Executive: :pay_ytd 
INPUT 'Expenses' ;Emp: : Expenses_ytd 


END SELECT 


Variant fields can appear anywhere within the RECORD. When you use 
RECORD variants, you imply that any RECORD instance can contain any 
one of the listed variants. Therefore, if each variant requires a different 
amount of space, VAX BASIC uses the case that requires the most storage 
to determine the space allocated for each RECORD instance. 


10.1.3 Accessing RECORD Components 


To access a particular elementary component within a RECORD that 
contains other groups, you use the name of the declared RECORD in- 
stance, the group name (or group names, if groups are nested), and the 
elementary component name, each separated by double colons (::). 


In the following example, the PRINT statement displays the Rig com- 
ponent in the Specifications group in the variable named My_yacht. The 
RECORD instance name qualifies the group name and the group name 
qualifies the elementary RECORD component. The elementary component 
name, qualified by all intermediate group names, and by the RECORD 
instance name, is called a fully qualified component. The full qualification 
of a component is called a component path name. 


Example 
DECLARE Yacht My_yacht 


PRINT My_yacht: :Specifications: :Rig 
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Because it is cumbersome to specify the entire component path name, 
VAX BASIC allows elliptical references to RECORD components. GROUP 
names are optional in the component path name unless: 

e A RECORD contains more than one component with the same name 


¢ The GROUP is an array 


The rules for using elliptical references are as follows: 

e¢ You must always specify the RECORD instance, that is, the name of 
the declared variable. 

e You must always specify any dimensioned group. 

e You may omit any other intermediate component names. 

¢ You must specify the final component name. 


The following example shows that using the complete component path 
name is valid but not required. The assignment statement uses the 
fully-qualified component name; the PRINT statement uses an elliptical 
reference to the same component, omitting Extended_family and Nuclear_ 
family GROUP names. Note that the Children GROUP name is required 
because the GROUP is an array; the elliptical reference to this component” 
must include the desired array element, in this case the second element of 
the Children array. 


Example 
! RECORD templates: 
RECORD Family 
GROUP Extended_family 
30 | 
30 


STRING Grandfather (1) 
STRING Grandmother (1) 


Two-element fixed-length string 
arrays for the names of maternal 
and paternal grandparents. 


GROUP Nuclear_family 


STRING Father = 30 
STRING Mother = 30 


Fixed-length strings for the nanes 
of parents. 


GROUP Children (10) 


An ii-element array for the names and 
gender of children. 


STRING Kid = 10 
STRING Gender = 1 


END GROUP Children 
END GROUP Nuclear_family 
END GROUP Extended_family 
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END RECORD 

! Declarations 

DECLARE Family My_family 

! Program logic starts here. 

My_family: :Extended_family: :Nuclear_family: :Children(1)::Kid = "Johnny" 
PRINT My_family: :Children(1): :Kid 

END 


Output 


Johnny 


Example 
! RECORD Templates. 


RECORD Test 
INTEGER Test_integers (2) ! 3-element array of integers. 
GROUP Group_1i ! Single GROUP containing: 
REAL My_number ! a real number and 
STRING Group_i_string ! a 16-character (default) string 
END GROUP 
GROUP Group_2(5) ! A 6-element GROUP, each element containing: 
INTEGER My_number ! an integer and 
DECIMAL Group_2_decimal ! a DECIMAL number. 
END GROUP 
END RECORD 
! Declarations 


DECLARE Test Array_of_test(10) ! Create an 11-element array of type Test... 
DECLARE Test Single_test ! ...and a separate single instance of type 
! Test. 


The minimal reference to the string Group_i_string in RECORD instance 
Array—of_test is as follows: 


Array_of_test (i) ::Group_i_string 


In this case, i is the subscript for array Array_of_test. Because the 
RECORD instance is itself an array, the reference must include a specific 
array element. 
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Because Single_test is not an array, the minimal reference to string 
Group__1_string in RECORD instance Single_test is as follows: 


Single_test: :Group_1_string 


The minimal reference for the REAL variable My_number in GROUP 
Group_1 in RECORD instance Array_of_test is as follows: 


Array_of_test (i): :Group_1: :My_number 


Here, i is the subscript for array Array_of_test. The minimal reference 
to the REAL variable My_number in RECORD instance Single_test is as 
follows: 


Single_test: :Group_1: :My_number 


Because there is a variable named My_number in groups Group_1 and 
Group_2, you must specify either Group_1::My_number or Group_2(i)::My— 
number. In this case, extra component names are required to resolve an 
otherwise ambiguous reference. 


The minimal reference to the DECIMAL variable Group_2_decimal in 
RECORD instances Array_of_test and Single_test are the fully qualified 
references. In the following examples, i is the subscript for array 
Array—of_test and j is an index into the group array Group_2. Even 
though Group_2_decimal is a unique component name within RECORD 
instance Single_test, the element of array Group_2 must be specified. In 
this case the extra components must be specified because each element of 
group Group_2 contains a component named Group_2_decimal. 


Array_of_test (i): :Group_2(j) : :Group_2_decimal 
Single_test: :Group_2(j) : :Group_2_decimal 
You can assign all the values from one RECORD instance to another 


RECORD instance, as long as the RECORD instances are identical except 
for names. 


In the following example, RECORD instances First__test1, Second_test1, 
and the individual elements of array Array_of_test1 have the same form: 
an array of four groups, each of which contains a 10-byte string variable, 
followed by a REAL variable, followed by an INTEGER variable. Any of 
these RECORD instances can be assigned to one another. 
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Example 

'RECORD Templates 

RECORD Testi 
GROUP Group_i(4) 


STRING My_string_1 = 10 
REAL My_real_1 
INTEGER My_integer_1 


END GROUP 
END RECORD 


RECORD Test2 
GROUP Group_2 


STRING My_string_2 = 10 
REAL My_real_2 
INTEGER My_integer_2 


END GROUP 
END RECORD 
RECORD Test3 


STRING My _string_3 = 10 
REAL My_real_3 
INTEGER My_integer_3 


END RECORD 
!Declarations 


DECLARE Testi First_testi, & 
Second_testi, & 
Array_of_test1(3) 


DECLARE Test2 First_test2 


DECLARE Test3 First_test3, & 
Array_of_test3(10) 


!Program logic starts here 

! A single RECORD instance is assigned to another single instance 
First_test1 = Second_testi 

! An array element is assigned to a single instance 

Second_testi = Array_of_test1(2) 


! And vice versa 
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Array_of_test1(2) = Second_testi 


Further, you can assign values from single RECORD instances to groups 
contained in other instances. 


In the following example, Array_of_test1 and First_test1 do not have 
the same form because Array_of_test1 is an array of RECORD Test1 and 
First_test1 is a single instance of RECORD Test1. Therefore, First _test1 
and Array_of_test1 cannot be assigned to one another. 


Example 
! A single instance is assigned to one group 
Array_of_test1(3)::Group_1(2) = First_test3 


! An array element is assigned a value from 
! a group contained in another array instance 


Array_of_test3(5) = Array_of_test1(3) : :Group_1(3) 
The examples shown in this chapter explain the mechanics of using 
data structures. See Chapter 14 for more information about using data 


structures as parameters. See Chapter 15 for more information about 
using data structures for file input and output. 
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Chapter 11 
Program Control 


VAX BASIC normally executes statements sequentially. Control statements 
let you change this sequence of execution. VAX BASIC control statements 
can alter the sequence of program execution at several levels: 


Statement modifiers control the execution of a single statement. 
Loops or decision blocks control the execution of a block of statements. 


Branching statements such as GOTO and ON GOTO pass control to 
statements or local subroutines. 

The EXIT and ITERATE statements explicitly control loops or decision 
blocks. 


The SLEEP, WAIT, STOP and END control statements suspend or halt 
the execution of your entire program. 


This chapter describes all of the VAX BASIC control statements. 


11.1 Statement Modifiers 


Statement modifiers are control structures that operate on a single state- 
ment. Statement modifiers let you execute a statement conditionally or 
create an implied loop. VAX BASIC has five statement modifiers: IF, 
UNLESS, FOR, UNTIL, and WHILE. 


A statement modifier affects only the statement immediately preceding it. 
You can modify only executable statements; declarative statements are not 
modifiable. 
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11.1.1 The IF Modifier 


The IF modifier tests a conditional expression. If the conditional expres- 
sion is true, VAX BASIC executes the statement. If it is false, VAX BASIC 
does not execute the modified statement but continues execution at the 
next program statement. The following is an example of a statement using 
the IF modifier: 


PRINT A IF (A < 5) 


11.1.2 The UNLESS Modifier 


The UNLESS modifier tests a conditional expression. VAX BASIC executes 
the modified statement only if the conditional expression is false. Like the 
IF modifier, the UNLESS modifier operates on a single statement: 


PRINT A UNLESS (A < 5) 
This is equivalent to 


PRINT A IF A >= 5 


11.1.3 The FOR Modifier 
The FOR modifier creates a loop on a single line. The following is an 
example of an implied loop created by a FOR modifier: 
A= A+ 4 FOR I% = 1% TO 10% 


11.1.4 The UNTIL Modifier 


The UNTIL modifier, like the FOR modifier, creates a single-line loop. 
However, instead of using a formal loop variable, you specify the termi- 
nating condition with a conditional expression. The modified statement 
executes repeatedly as long as the condition is false. For example: 


= B+ 1 UNTIL (A - B) < 0.0001 


Because of precision limitations, you should not use real number calcula- 
tions in UNTIL loops. For example: 


Z = Z + 1 UNTIL Z/5 = 100 
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Because Z/5 may never exactly equal 100, the loop could execute 
indefinitely. 


11.1.5 The WHILE Modifier 


The WHILE modifier repeats a statement as long as a conditional ex- 
pression is true. Like the UNTIL and FOR modifiers, it lets you create 
single-line loops. In the following example, VAX BASIC replaces the value 
of A with A/2 as long as the absolute value of A is greater than 1/10. 
Note that you can inadvertently create an infinite loop if the terminating 
condition is never reached. 


A =A / 2 WHILE ABS(A) > 0.1 


11.1.6 Nesting Modifiers 


You can append more than one modifier to a statement. This is called 
nesting modifiers. VAX BASIC evaluates nested modifiers from right to 
left. If the test of the rightmost modifier fails, control passes to the next 
statement, not to the preceding modifier on the same line. 


In the following example, VAX BASIC first tests the rightmost modifier 
of the first PRINT statement. Because this condition is false, VAX BASIC 
executes the following PRINT statement and tests the rightmost modifier. 
Because this condition is met, VAX BASIC tests the leftmost modifier 

of the same PRINT statement. This condition, however, is not met. 
Therefore, VAX BASIC executes the following PRINT statement. Because 
both conditions are met in the third PRINT statement, VAX BASIC prints 
the value of C. 


Example 


A 
B 
Cc 


PRINT "A =";A IF A = 5 UNLESS C = 1 
PRINT “"B =";B UNLESS C = 15 IF B 
PRINT "C =";C IF B = 10 UNLESS C 
END 


5 
10 
15 


5 
10 
5 


Output 


c = 15 
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11.2 Loops 


Loops allow you to repeat the execution of a set of statements. This set 
of statements is called a loop block. There are three types of VAX BASIC 
program loops: 


FOR...NEXT 
WHILE...NEXT 
UNTIL...NEXT 


If you know how many times you want a loop to execute, that is, the 
number of iterations, you can use a FOR...NEXT loop. If you do not know 
the exact number of iterations when the loop begins execution, you can 
use either a WHILE...NEXT or an UNTIL...NEXT loop. 


Note that all of these types of loops can be nested, that is, lexically located 
one inside another. 


11.2.1 FOR...NEXT Loops 


In a FOR...NEXT loop, you specify a loop control variable (the loop index) 
that determines the number of loop iterations. This number must be a 
scalar (unsubscripted) variable. When VAX BASIC begins execution of 

a FOR...NEXT loop, the starting and ending values of the loop control 
variable are known. 


The FOR statement assigns the control variable a starting value and a 
terminating value. You can use the optional STEP clause to specify the 
amount to be added to the loop control variable after each loop iteration. 


When a FOR loop block executes, the VAX BASIC compiler does the 
following: 


i 
2 


3. 
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Evaluates the starting value and assigns it to the control variable. 


Evaluates the ending value and the step value and assigns these 
results to temporary storage locations. 


Tests whether the ending value has been exceeded. If the ending 
value has already been exceeded, VAX BASIC executes the statement 
following the NEXT statement. If the ending value has not been 
exceeded, VAX BASIC executes the statements in the loop. 


4. Adds the step value to the control variable and transfers control 
to the FOR statement, which tests whether the ending value has 
been exceeded. Steps 3 and 4 are repeated until the ending value is 
exceeded. 


Note that VAX BASIC performs the test before the loop executes. When 
the control variable exceeds the ending value, VAX BASIC exits the loop, 
and then subtracts the step value from the control variable. This means 
that after loop execution, the value of the control variable is the value 
last used in the loop, not the value that caused loop termination. If the 
starting value is greater than the ending value, and the step value is 
positive, the loop will not execute. 


Example 1 assigns the values 1 through 10 to consecutive array elements 
1 through 10 of New_array, whereas Example 2 assigns consecutive 
multiples of 2 to the odd-numbered elements of New_array. 


Example 1 


FOR I% = 1% TO 10% 
New_array(I%) = I% 
NEXT I% 


Example 2 


FOR I% = 1% TO 10% STEP 2 
New_array(I%) = 1% + 1% 
NEXT I% 


Note that the starting, ending, and step values can be run-time expressions. 
You can have VAX BASIC calculate these values when the program runs, 
as opposed to using a constant value. For instance, the following example 
assigns sales information to array Sales_data. The number of iterations 
depends on the value of the variable Days_in_month, which represents 
the number of days in that particular month. 


Example 


FOR I% = 1% TO Days_in_month 
Sales_data(I%) = Quantity_sold 
NEXT I% 


Because the starting, ending, and step values can be numeric expressions, 
they are not evaluated until the program runs. This means that you can 
have a FOR...NEXT loop that does not execute. The following example 
prompts the user for the starting, ending, and step values for a loop, and 
then tries to execute that loop. The loop executes zero times because it is 
impossible to go from 0 to 5 using a step value of -1. 
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Example 
counter% = 0% 


INPUT "Start"; start/, 
INPUT "Finish"; finish%, 
INPUT "Step value"; step_val7 


FOR I% = start% TO finish, STEP step_valy, 
_counter% = counter% + 1% 
NEXT I% 


PRINT "This loop executed"; counter4; "times." 


Output 


Start? 0 

Finish? 5 

Step value? -1 

This loop executed O times. 


Whenever possible, you should use integer variables to control the execu- 
tion of FOR...NEXT loops because some decimal fractions cannot be repre- 
sented exactly in a binary computer, and the calculation of floating-point 
control variables is subject to this inherent imprecision. 


In the following example, the first loop uses an integer control variable 
while the second uses a floating-point control variable. The first loop 
executes 100 times and the second 99 times. After the ninety-ninth 
iteration of the second loop, the internal representation of the value 

of Floating_point_variable exceeds 10 and VAX BASIC exits the loop. 
Because the first loop uses integer values to control execution, VAX BASIC 
does not exit the loop until Integer_variable equals 100. 


Example 


Loop_count_1 = 0% 
Loop_count_2 = 0% 


FOR Integer_variable = 1% to 100% STEP 1% 
Loop_count_i = Loop_count_1 + 1% 
NEXT Integer_variable 


FOR Floating_point_variable = 0.1 to 10 STEP 0.1 
Loop_count_2 = Loop_count_2 + 1% 
NEXT Floating_point_variable 
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PRINT "Integer loop count:"; Loop_count_1 
PRINT "Integer loop end :"; Integer_variable 
PRINT "Real loop count: "; Loop_count_2 


PRINT "Real loop end: "; Floating_point_variable 
Output 

Integer loop count: 100 

Integer loop end: 100 

Real loop count: 99 

Real loop end: 9.9 


If you need to use floating-point values in a loop, you should initialize a 
floating-point variable and increment it within the loop. 


Example 


Real_counter = 0.1 

Count_loop: 

FOR Integer_variable = 1% TO 100000% 
Real_counter = Real_counter + .1 

NEXT Integer_variable 


Although it is not recommended programming practice, you can assign 

a value to a FOR...NEXT loop’s control variable while in the loop. This 
affects the number of times a loop executes. For example, assigning 

a value that exceeds the ending value of a loop will cause the loop’s 
execution to end as soon as VAX BASIC performs the termination test in 
the FOR statement. Assigning values to ending or step variables, however, 
has no effect at all on the loop’s execution. 


11.2.2 WHILE...NEXT Loops 


A WHILE...NEXT statement uses a conditional expression to control loop 
execution; the loop is executed as long as a given condition is true. A 
WHILE...NEXT loop is useful when you do not know how many loop 
iterations are required. 


In the following example, the first statement tells the user to input data 
and then type DONE when he is finished. After the user enters the 

first piece of input, VAX BASIC executes the WHILE...NEXT loop. If 

the first input value is not “DONE”, the loop executes and prompts the 
user for another input value. Once the user enters this input value, the 
WHILE...NEXT loop once again checks to see if this value corresponds to 
“DONE”. The loop will continue executing until the user types “DONE” in 
response to the prompt. 
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Example 
INPUT 'Type "DONE" when finished'; Answer 
WHILE (Answer <> "DONE") 


INPUT "More data"; Answer 
NEXT 


Note that the NEXT statement in the WHILE...NEXT and UNTIL...NEXT 
loops does not increment a control variable; your program must change a 
variable in the conditional expression or the loop will execute indefinitely. 


The evaluation of the conditional expression determines whether the loop 
executes. The test is performed (that is, the conditional expression is 
evaluated) before the first iteration; if the value is false (0), the loop does 
not execute. 


It can be useful to intentionally create an infinite loop by coding a 
WHILE...NEXT loop whose conditional expression is always true. Of 
course, when doing this, you must still take care to provide a way out of 
the loop. You can do this with an EXIT statement or by trapping a run- 
time error. See Chapter 17 for more information about trapping run-time 
errors. 


11.2.3 UNTIL...NEXT Loops 


The UNTIL...NEXT loop behaves exactly like a WHILE...NEXT loop, 
except that the logical sense of the conditional expression is reversed; that 
is, the UNTIL...NEXT loop executes until a given condition is true. 


An UNTIL...NEXT loop executes repeatedly for as long as the conditional 
expression is false. Note that in UNTIL...NEXT and WHILE...NEXT loops, 
the NEXT statement does not increment a control variable. You must 
explicitly change a variable in the conditional expression or the loop will 
execute indefinitely. 


It is possible to code the example in Section 11.2.2 as an UNTIL...NEXT 
loop as shown in the following example. These loops are equivalent 
except for the logical sense of the termination test (WHILE Answer <> 
“DONE?” as opposed to UNTIL Answer = “DONE?’). 
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Example 
INPUT ‘Type "DONE" when finished.'; Answer 
UNTIL (Answer = "DONE") 


INPUT "More data"; Answer 
NEXT 


UNTIL and FOR loops differ because VAX BASIC exits UNTIL loops as 
soon as the test for the terminating condition is met. This test occurs 
after VAX BASIC executes the NEXT statement and before it executes the 
UNTIL statement. For example, the following loop executes 10 times. 
When VAX BASIC exits the FOR loop, J% equals 10. 


Example 


FOR J% = 1% to 10% 
A=A+e+ti1 
PRINT A 

NEXT J% 


The following UNTIL loop executes only nine times. After the ninth 
iteration, the conditional expression is true; control then passes out of the 
loop. 


Example 


Jh = 1% 
UNTIL J%Z = 10% 
PRINT J% 
JA = JL + 1% 
NEXT 


11.2.4 Nesting Loops 


When a loop block is entirely contained in another loop block, it is called 
a nested loop. 


The following example declares a two-dimensional array and uses nested 
FOR...NEXT loops to fill the array elements with sales information. The 
inner loop executes 16 times for each iteration of the outer loop. This 
example assigns a value to each of the 256 elements of the array. 
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Example 


DECLARE 
INTEGER 
Column_number , 
Row_number 
REAL 
Sales_info, 
Two_dim_array (15%, 15%) 


FOR Row_number = 0% TO 15% 
FOR Column_number = 0% to 15% 
INPUT "Please enter the sales information" ;Sales_info 
Two_dim_array (Row_number, Column_number) = Sales_info 
NEXT Column_number 
NEXT Row_number 


Note that in nested loops the inner loop is entirely contained in the outer 
loop: nested loops cannot overlap. 


11.3 Unconditional Branching (the GOTO Statement) 


The GOTO statement specifies which program line the VAX BASIC com- 
piler is to execute next, regardless of that line’s position in the program. 
If the statement at the target line number or label is nonexecutable (such 
as a REM statement), VAX BASIC transfers control to the next executable 
statement following the target line number. 


You can use a GOTO statement to exit from a loop; however, it is better 
programming practice to use the EXIT statement. 


11.4 Conditional Branching 


Conditional branching is the transfer of program control only when 
specified conditions are met. There are three VAX BASIC statements 
that let you conditionally transfer control to a target statement in your 
program: 

e The ON...GOTO...OTHERWISE statement 

e = The IF... THEN...ELSE statement 


e The SELECT...CASE statement 
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11.4.1. The ON...GOTO...0OTHERWISE Statement 


In the ON...GOTO...OTHERWISE statement, VAX BASIC tests the value 
specified after the ON keyword. If the value is 1, VAX BASIC transfers 
control to the first target in the list; if the value is 2, control passes to the 
second target, and so on. If the value is less than 1, or greater than the 
number of targets in the list, VAX BASIC transfers control to the target 
specified in the OTHERWISE clause. 


Menu: 
PRINT "Would you like to change:" 
PRINT "1. First name" 
PRINT "2. Last name" 


INPUT CHOICEY 


ON CHOICE% GOTO First_name, Last_name OTHERWISE Other_choice 


First_name: 
INPUT "First name"; firstname$ 
GOTO Done 


Last_name: 
INPUT "Last name"; lastname$ 
GOTO Done 


Other_choice: 
PRINT "Invalid choice" 
PRINT "Let's try again" 
GOTO Menu 


Done: 
END 


Note that if you do not supply an OTHERWISE clause and the control 
variable is less than 1 or greater than the number of targets, VAX BASIC 
signals “ON statement out of range (ERR = 58)’. 
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11.4.2 The IF...THEN...ELSE Statement 


The IF...THEN...ELSE statement evaluates a conditional expression and 
uses the result to determine which block of statements to execute next. 
If the conditional expression is true, VAX BASIC executes the statements 
in the THEN clause. If the conditional expression is false, VAX BASIC 
executes the statements in the ELSE clause, if one is present. If the 
conditional expression is false and there is no ELSE clause, VAX BASIC 
executes the statement immediately following the END IF statement. 


In the following example, VAX BASIC evaluates the conditional expression 
number < 0. If the input value of number is less than zero, the conditional 
expression is true. VAX BASIC then executes the four statements in the 
THEN clause and skips the statement in the ELSE clause. VAX BASIC 
transfers control to the statement following the END IF. If the value of 
number is greater than or equal to zero, the conditional expression is false. 
VAX BASIC then skips the statements in the THEN clause and executes 
the statement in the ELSE clause. 


Example 
INPUT "Input number"; number 


IF (number < 0) 
THEN 
number = number * (-1) 
PRINT "That square root is imaginary" 
PRINT "The square root of its absolute value is"; 
PRINT SQR (number) 
ELSE 
PRINT "The square root is"; SQR(number) 
END IF 
END 


Output 


Input number? -9 
That square root is imaginary 
The square root of its absolute value is 3 


One of the most common programming errors is neglecting to terminate 
an IF...THEN...ELSE statement. After an IF block is executed, control is 
transferred to the statement immediately following the END IF. If there is 
no END IF, VAX BASIC transfers control to the next line number. When 
this happens, any code between the keyword ELSE and the next line 
number becomes part of the ELSE clause. If there are no line numbers, 
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the VAX BASIC compiler ignores the remaining program code from the 
keyword ELSE to the end of the program. Therefore it is very important 
that you always use END IF to terminate IF statements. 


In the following example, the first IF... THEN...ELSE statement is ter- 
minated by END IF, and therefore works as expected. Because the 
second IF...THEN...ELSE statement is not terminated by END IF, the 
VAX BASIC compiler assumes that the last PRINT statement in the pro- 
gram is part of the second ELSE clause. When you run this program, the 
first IF... THEN...ELSE statement will always execute correctly. However, 
the final PRINT statement will execute only when the value of On_off_val 
is 1, because the compiler considers this PRINT statement to be part of the 
second ELSE clause. 


Example 


10 DECLARE INTEGER light_bulb 
DECLARE INTEGER circuit_switch 
DECLARE INTEGER CONSTANT Opened = 0 
DECLARE INTEGER CONSTANT Closed = 1 


PRINT "Please enter zero or one, corresponding to the circuit" 
PRINT “switch being open or closed" 
INPUT On_off_val 


IF On_off_val = Opened 
THEN 
PRINT “The light bulb is off." 
ELSE 
PRINT "The light bulb is on." 
END IF 


IF On_off_val = Closed 
THEN 
PRINT "The light bulb is on." 
ELSE 
PRINT "The light bulb is off." 
PRINT "That's all for now." 
20 END 
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Output 1 


Please enter zero or one, corresponding to the circuit 
switch being open or closed 

70 

The light bulb is off. 

The light bulb is off. 

That's all for now. 


Output 2 


Please enter zero or one, corresponding to the circuit 
switch being open or closed 

71 

The light bulb is on. 

The light bulb is on. 


Note that a statement in a THEN or ELSE clause can be followed by a 
modifier. In this case, the modifying IF applies only to the statement that 
immediately precedes it: 


Example 


IF A=B 
THEN 

PRINT A IF A= 3 
ELSE 

PRINT B IF B > 0 
END IF 


11.4.3 The SELECT...CASE Statement 


The SELECT...CASE statement lets you specify an expression (the SELECT 
expression), any number of possible values (cases) for the SELECT expres- 
sion, and a list of statements (a CASE block) for each case. The SELECT 
expression can be a numeric or string value. CASE values can be single 
or multiple values, one or more ranges of values, or relationships. When 
a match is found between the SELECT expression and a CASE value, the 
statements in the following CASE block are executed. Control is then 
transferred to the statement following the END SELECT statement. 


In the following example, the CASE values appear to overlap; that is, the 
CASE value that tests for values greater than or equal to 0.5 also includes 
the values greater than or equal to 1.0. However, VAX BASIC executes 
the statements associated with the first matching CASE statement and 
then transfers control to the statement following END SELECT. In this 
program, each range of values is tested before it overlaps in the next range. 
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Because the compiler executes the first matching CASE statement, the 
overlapping values do not matter. 


Example 
DECLARE REAL Stock_change 


INPUT "Please enter stock price change" ;Stock_change 


SELECT Stock _change 


CASE <= 0.5 
PRINT "Don't sell yet." 


CASE <= 1.0 
PRINT "Sell today." 


CASE ELSE 
PRINT "Sell NOW!" 


END SELECT 
END 


Output 


Please enter stock price change? 2.1 
Sell NOW! 


If no match is found for any of the specified cases and there is no CASE 
ELSE block, VAX BASIC transfers control to the statement following END 
SELECT without executing any of the statements in the SELECT block. 


SELECT...CASE is powerful because it lets you use run-time expressions 
for both SELECT expressions and CASE values. The following example 
uses VAX BASIC built-in string functions to examine command input. 


Example 


! This program is a skeleton command processor. 
! It recognizes three VAX BASIC environment commands: 


! 

! SAVE 
! SCRATCH 
! OLD 


DECLARE INTEGER CONSTANT True 
DECLARE INTEGER CONSTANT False 


-1 
0 


DECLARE STRING CONSTANT Null_input = "" !This is the null string. 
DECLARE STRING Command 
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! Main program logic starts here. 
Command_loop: 


WHILE True ! This loop executes until the user types only a 
! carriage return in response to the prompt. 


PRINT 

PRINT "Please enter a command (uppercase only)." 
PRINT "Type a carriage return when finished." 
INPUT Command 

PRINT 


SELECT Command 


CASE Null_input ! If user types RETURN, 
! exit from the loop 
GOTO Done ! and end the progran. 


! The next three cases use the SEG$ and LEN string functions. 

! LEN returns the length of the typed string, and SEG$ searches 
! the string literals ("SAVE", "SCRATCH", and "OLD") for a 

! match up to that length. Note that if the user types an "S", 
! it is interpreted as a SAVE command only because SAVE is the 
! first case tested. 


CASE SEG$ ( "SAVE", 1%, LEN (Command) ) 
PRINT "That was a SAVE command." 


CASE SEG$ ( "SCRATCH", 1%, LEN (Command) ) 
PRINT "That was a SCRATCH command." 


CASE SEG$( "OLD", 1%, LEN (Command) ) 
PRINT "That was an OLD command." 


CASE ELSE 
PRINT "Invalid command, please try again." 


END SELECT 
NEXT 


Done: 
END 


11.5 The EXIT and ITERATE Statements 


This section describes the EXIT and ITERATE statements and shows their 
use with nested control structures. 


The ITERATE and EXIT statements let you explicitly control loop execu- 
tion. These statements can be used to transfer control to the top or bottom 
of a control structure. 
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You can use EXIT to transfer control out of any of these structures: 


e ~=FOR...NEXT loops 

e = WHILE...NEXT loops 

e UNTIL...NEXT loops 

e IF...THEN...ELSE blocks 

e SELECT...CASE blocks 

e SUB, FUNCTION and PICTURE subprograms 
e DEF functions, and programs 


In the case of control structures, EXIT passes control to the first statement 
following the end of the control structure. 


You can use ITERATE to explicitly reexecute a FOR...NEXT, WHILE...NEXT, 
or UNTIL...NEXT loop. EXIT and ITERATE statements can appear only 
within the code blocks you wish to leave or reexecute. 


Executing the ITERATE statement is equivalent to transferring control to 
the loop’s NEXT statement. The termination test is still performed when 
the NEXT statement transfers control to the top of the loop. In addition, 
transferring control to the NEXT statement means that a FOR loop’s 
control variable is incremented. 


Supplying a label for every loop lets you state explicitly which loop 

to leave or reexecute. If you do not supply a label for the ITERATE 
statement, VAX BASIC reexecutes the innermost active loop. For example, 
if an ITERATE statement (that does not specify a label) is executed in the 
innermost of three nested loops, only the innermost loop is reexecuted. 


In contrast, labeling each loop and supplying a label argument to the 
ITERATE statement lets you reexecute any of the loops. A label name also 
helps document your code. Because you must use a label with EXIT and 
it is sometimes necessary to use a label with ITERATE, you should always 
label the structures you want to control with these statements. 


The following example shows the use of both the EXIT and ITERATE 
statements. This program explicitly exits the loop if you type a carriage 
return in response to the prompt. If you type a string, the program prints 
the length of the string and explicitly reexecutes the loop. 
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Example 
DECLARE STRING User_string 


Read_loop: 
WHILE 1% = 1% 
LINPUT “Please type a string"; User_string 


IF User_string == "" 
THEN 
EXIT Read_loop 
ELSE 


PRINT "Length is ";LEN(User_string) 
ITERATE Read_loop 
END IF 
NEXT 
END 


11.6 Executing Local Subroutines 


In VAX BASIC, a subroutine is a block of code accessed by a GOSUB 
or ON GOSUB statement. It must be in the same program unit as the 
statement that calls it. The RETURN statement in the subroutine returns 
control to the statement immediately following the GOSUB. 


The first line of a subroutine can be any valid VAX BASIC statement, 
including a REM statement. You do not have to transfer control to the 
first line of the subroutine. Instead, you can include several entry points 
into the same subroutine. You can also reference subroutines by using a 
GOSUB or ON GOSUB statement to another subroutine. 


Variables and data in a subroutine are global to the program unit in which 
the subroutine resides. 


11.6.1 The GOSUB and RETURN Statements 


The GOSUB statement unconditionally transfers control to a line in a 
subroutine. The last statement in a subroutine is a RETURN statement, 
which returns control to the first statement after the calling GOSUB. A 
subroutine can contain more than one RETURN statement so you can 
return control conditionally, depending on a specified condition. 
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The following example first assigns a value of 5 to the variable A, then 
transfers control to the subroutine labeled Times_two. This subroutine 
replaces the value of A with A multiplied by 2. The subroutine’s RETURN 
statement transfers control to the first PRINT statement, which displays 
the changed value. The program calls the subroutine two more times, 
with different values for A. Each time, the RETURN transfers control to 
the statement immediately following the corresponding GOSUB. 


Example 


A=5 
GOSUB Times_two 
PRINT A 


A = 15 
GOSUB Times_two 
PRINT A 


A = 25 
GOSUB Times_two 
PRINT A 


GOTO Done 


Times_two: 
!This is the subroutine entry point 
A=A¥*2 
RETURN 


Done: 
END 
Output 


10 
30 
50 


Note that VAX BASIC signals “RETURN without GOSUB” if it encounters 
a RETURN statement without first having encountered a GOSUB or ON 
GOSUB statement. 
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11.6.2 The ON...GOSUB...OTHERWISE Statement 


The ON...GOSUB...OTHERWISE statement transfers control to one of 
several target subroutines depending on the value of a numeric expression. 
A RETURN statement returns control to the first statement after the calling 
ON GOSUB. A subroutine can contain more than one RETURN statement 
so that you can return control conditionally, depending on a specified 
condition. 


VAX BASIC tests the value of the integer expression. If the value is 1, 
control transfers to the first line number or label in the list; if the value 

is 2, control passes to the second line number or label, and so on. If 

the control variable’s value is less than 1 or greater than the number 

of targets in the list, VAX BASIC transfers control to the line number 

of label specified in the OTHERWISE clause. If you do not supply an 
OTHERWISE clause and the control variable’s value is less than 1 or 
greater than the number of targets, VAX BASIC signals “ON statement out 
of range (ERR = 58)”. 


Example 


INPUT "Please enter first integer value"; First_value% 
INPUT "Please enter second integer value"; Second_value% 


Choice: 
PRINT "Do you want to perform:" 
PRINT "1. Multiplication" 
PRINT "2. Division" 
PRINT "3. Exponentiation" 


INPUT Selection/% 


ON Selection, GOSUB Mult, Div, Expon OTHERWISE Wrong 
GOTO Done 


Mult: 
Result% = First_value% * Second_value% 
PRINT Result% 
RETURN 


Div: 
Result% = First_value / Second_value% 
PRINT Result% 
RETURN 


Expon: 
Result% = First_value% ** Second_value% 
PRINT Result% 
RETURN 
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Wrong: 
PRINT "Invalid selection" 
RETURN 


Done: 
END 


11.7 Suspending and Halting Program Execution 


There are two VAX BASIC statements that you can use to suspend pro- 
gram execution: 


e SLEEP 
e WAIT 


These statements cause VAX BASIC either to suspend program execution 
for a specified time or to wait a certain period of time for user input. 


After execution of the last statement, a VAX BASIC program automatically 
halts and closes all files. However, you can explicitly halt program 
execution by using one of the following statements: 


e STOP 

e END 

The STOP statement does not close files. It can appear anywhere in a 
program. The END statement closes files and must be the last statement in 


a main program. For more information on the STOP and END statements, 
see Section 11.7.3 and Section 11.7.4. 


11.7.1 The SLEEP Statement 


The SLEEP statement suspends program execution for a specified number 
of seconds. The following program waits two minutes (120 seconds) after 
receiving the input string, and then prints it. 
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Example 


INPUT "Type a string of characters"; C$ 
SLEEP 120% 

PRINT C$ 

END 


The SLEEP statement is useful if you have a program that depends on 
another program for data. Instead of constantly checking for a condition, 
the SLEEP statement lets you check the condition at specified intervals. 


11.7.2 The WAIT Statement 


You use the WAIT statement only with terminal input statements such 
as INPUT, INPUT LINE, and LINPUT. For example, the following pro- 
gram prompts for input, then waits 30 seconds for your response. If the 
program does not receive input in the specified time, VAX BASIC signals 
“Keyboard wait exhausted (ERR = 15)” and exits the program. 


Example 


WAIT 30% 
INPUT "You have 30 seconds to type your password"; PSW$ 
END 


The WAIT statement affects all subsequent INPUT, INPUT LINE, LINPUT, 
MAT INPUT, and MAT LINPUT statements. To disable a previously 
specified WAIT statement, use WAIT 0%. 


In the following example, the first WAIT statement causes the first INPUT 
statement to wait 30 seconds for a response. The WAIT 0% statement 
disables this 30-second requirement for all subsequent INPUT statements. 


Example 


WAIT 30% 

INPUT "You have 30 seconds to type your password"; PSW$ 
WAIT 0% 

INPUT "What directory do you want to go to"; DIR$ 


11.7.3 The STOP Statement 


The STOP statement is a debugging tool that lets you check the flow of 
program logic. STOP suspends program execution but does not close files. 
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When VAX BASIC executes a STOP statement, it signals “STOP at line 
<line-num> ”. If the program executes in the BASIC environment, VAX 
BASIC then prompts with the DCL command level prompt. In response, 
you can type: 


¢ Immediate mode statements (to examine or change program values) 
¢ The CONTINUE statement (to continue program execution) 


You use the STOP statement when debugging in immediate mode in 
the BASIC environment. For more information on immediate mode 
statements, see Chapter 3 in this manual. 


If you compile, link, and execute a program containing a STOP statement 
at DCL command level, VAX BASIC displays a number sign (#) prompt 
when the STOP statement is encountered. At this point, you can type: 


e CONTINUE (to continue program execution) 
e EXIT (to return to DCL command level) 


11.7.4 The END Statement 


The END statement marks the end of a main program. When VAX BASIC 
executes an END statement it closes all files and halts program execution. 


The END statement is optional in VAX BASIC programs. However, you 
should include it for good programming practice. The END statement 
must be the last statement in the main program. 


If you run your program in the BASIC environment, the END statement 
returns you to VAX BASIC command level. If you execute the program 
outside the BASIC environment, the END statement returns you to DCL 
command level. 
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Chapter 12 
Functions 


A function is a single statement or group of statements that perform 
operations on operands and return the result to your program. VAX 
BASIC has built-in functions that perform numeric and string operations, 
conversions, and date and time operations. This chapter describes only a 
selected group of built-in functions. For a complete description of all VAX 
BASIC built-in functions, see the VAX BASIC Reference Manual. 


This chapter also describes user-defined functions. VAX BASIC lets you 
define your own functions in two ways: 


e¢ With the DEF statement 
e As separately compiled subprograms (external functions) 


DEF function definitions are local to a program module, while external 
functions can be accessed by any program module. You create local 
functions with the DEF statement and optionally declare them with the 
DECLARE statement. You create external functions with the FUNCTION 
statement and declare them with the EXTERNAL statement. For more 
information on creating external functions with the FUNCTION statement, 
see Chapter 14. 


Once you have created and declared a function, you can invoke it just as 
you would a built-in function. 


12.1 Built-in Functions 


The functions described in this section let you perform sophisticated 
manipulations of string and numeric data. VAX BASIC also provides 
algebraic, exponential, trigonometric, and randomizing mathematical 
functions. 
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12.1.1 Numeric Functions 


Numeric functions generally return a result of the same data type as the 
function’s parameter. For example, if you pass a DOUBLE argument to 
any of the trigonometric functions, they return a DOUBLE result. 


If the format of a VAX BASIC function specifies an argument of a partic- 
ular data type, VAX BASIC converts the actual argument supplied to the 
specified data type. For instance, if you supply an integer argument to a 
function that expects a floating-point number, VAX BASIC converts the 
argument to floating-point. Floating-point arguments that are passed to 
integer functions are truncated, not rounded. 


The following are some examples of VAX BASIC built-in numeric 
functions. 


12.1.1.1 The ABS Function 
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The ABS function returns a floating-point number that equals the absolute 
value of a specified numeric expression. The following is an example of 
the ABS function: 


Example 

READ A,B 

DATA 10,-35.3 
NEW_A = ABS(A) 
PRINT NEW_A; ABS(B) 
END 

Output 


10 35.3 


ABS always returns a number of the default floating-point data type. 


12.1.1.2 The INT and FIX Functions 


The INT function returns the floating-point value of the largest integer less 
than or equal to a specified expression. INT always returns a number of 
the default floating-point type. 


The FIX function truncates the value of a floating-point number at the 
decimal point. FIX always returns a number of the default floating-point 


type. 


The following example points out the differences between the INT and 
FIX functions. Note that the value returned by FIX(-45.3) differs from the 
value returned by INT(-45.3). 


Example 


PRINT INT(23.553); FIX(23.553) 
PRINT INT(3.1); FIX(3.1) 
PRINT INT(-45.3); FIX(-45.3) 
PRINT INT(-11); FIX(-11) 

END 


Output 


23 «23 
3 3 
-46 -45 
-11 -11 


12.1.1.3 The SIN, COS, and TAN Functions 


The SIN, COS, and TAN functions return the sine, cosine, and tangents 
of an angle in radians or degrees, depending on which angle clause 
you choose with the OPTION statement. If you supply a floating-point 
argument to the SIN, COS, and TAN functions, they return a number of 
the same floating-point type. If you supply an integer argument, they 
convert the argument to the default floating-point data type and return a 
floating-point number of that type. 


The following program accepts an angle in degrees, converts the angle to 
radians, and prints the angle’s sine, cosine, and tangent. 
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Example 


!CONVERT ANGLE (X) TO RADIANS, AND 

!FIND SIN, COS AND TAN 

PRINT "DEGREES", "RADIANS", "SINE", "COSINE", "TANGENT" 
FOR I% = 0% TO 5% 


READ X 
LET Y = X * 2 * PI / 360 
PRINT 
PRINT X ,Y ,SIN(Y) ,COS(Y) ,TAN(Y) 
NEXT I% 
DATA 0,10,20,30,360,45 
END 
Output 
DEGREES RADIANS SINE COSINE TANGENT 
0 0 0 1 0 
10 174533 173648 . 984808 . 176327 
20 . 349068 34202 . 939693 . 36397 
30 . 523599 5 . 866025 .57735 
360 6.28319 .174846E-06 1 .174846E-06 
45 . 785398 .707107 .707107 1 


NOTE 


As an angle approaches 90 degrees (PI/2 radians), 270 degrees 
(3*PI/2 radians), 450 degrees (5*PI/2 radians) and so on, the 
tangent of that angle approaches infinity. If your program 
tries to find the tangent of such an angle, VAX BASIC signals 
“Division by 0” (ERR=61). 


2.1.1.4 The LOG10 Function 
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A logarithm is the exponent of some number (called a base). Common 
logarithms use the base 10. The common logarithm of a number n, for 
example, is the power to which 10 must be raised to equal n. For example, 
the common logarithm of 100 is 2, because 10 raised to the power 2 equals 
100. 


The LOG10 function returns a number’s common logarithm. The follow- 
ing example calculates the common logarithms of all multiples of 10 from 
10 to 100 inclusive: 


Example 


FOR I% = 10% TO 100% STEP 10% 
PRINT LOG10(1%) 

NEXT I% 

END 


Output 


. 30103 
-47712 
- 60206 
. 69897 
. 77815 
.8451 

. 90309 
.95424 


ee ee oe a a 


we 


If you supply a floating-point argument to LOG10, the function returns 
a floating-point number of the same data type. If you supply an integer 
argument, LOG10 converts it to the default floating-point data type and 
returns a value of that type. 


12.1.1.5 The EXP Function 


The EXP function returns the value of e raised to a specified power. The 
following example prints the value of e and e raised to the second power: 


Example 


READ A,B 

DATA 1,2 

PRINT 'e RAISED TO THE POWER'; A; " EQUALS"; EXP(A) 
PRINT 'e RAISED TO THE POWER'; B; " EQUALS"; EXP(B) 
END 


Output 


e RAISED TO THE POWER 1 EQUALS 2.71828 
e RAISED TO THE POWER 2 EQUALS 7.38906 


If you supply a floating-point argument to EXP, the function returns a 
floating-point number of the same data type. If you supply an integer 
argument, EXP converts it to the default floating-point data type and 
returns a value of that type. 
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12.1.1.6 The RND Function 
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The RND function returns a number greater than or equal to zero and less 
than 1. The RND function always returns a floating-point number of the 
default floating-point data type. The RND function generates seemingly 
unrelated numbers. However, given the same starting conditions, a 
computer always gives the same results. Each time you execute a program 
with the RND function, you receive the same results. 

Example 

PRINT RND,RND,RND,RND 

END 

Output 1 


- 76308 . 179978 - 902878 -88984 


Output 2 
.76308 .179978 .902878 . 88984 


With the RANDOMIZE statement, you can change the RND function’s 
starting condition and generate truly random numbers. To do this, place a 
RANDOMIZE statement before the line invoking the RND function. Note 
that the RANDOMIZE statement should be used only once in a program. 
With the RANDOMIZE statement, each invocation of RND returns a new 
and unpredictable number. 


Example 
RANDOMIZE 


PRINT RND,RND,RND,RND 
END 


Output 1 
. 403732 . 34971 . 15302 92462 


Output 2 
404165 . 272398 . 261667 . 10209 


The RND function can generate a series of random numbers over any 
open range. To produce random numbers in the open range A to B, use 
the following formula: 


(B-A)*RND + A 


The following program produces 10 numbers in the open range 4 to 6: 


Example 


FOR I% = 1% TO 10% 

PRINT (6%-4%) * RND + 4 
NEXT I% 
END 


Output 


5.52616 
4.35996 
5.80576 
5.77968 
4.77402 
4.95189 
5.76439 
4.37156 
5.2776 

4.53843 


12.1.2 Data Conversion Functions 


VAX BASIC provides built-in functions that can: 
e Convert a 1-character string to the character’s ASCII value and vice 
versa 


e Translate strings from one data format to another, for example, 
EBCDIC to ASCII 


The following sections describe some of these functions. 


12.1.2.1 The ASCII Function 


The ASCII function returns the numeric ASCII value of a string’s first 
character. The ASCII function returns an integer value between 0 and 255, 
inclusive. For instance, in the following example, the PRINT statement 
prints the integer value 66 because this is the ASCII value equivalent of 
an uppercase B, the first character in the string. 
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Example 
test_string$ = "BAT" 


PRINT ASCII (test_string$) 
END 


Output 
66 
Note that the ASCII value of a null string is zero. 


12.1.2.2 The CHR§$ Function 
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The CHR$ function returns the character whose ASCII value you supply. 
If the ASCII integer expression that you supply is less than zero or greater 
than 255, VAX BASIC treats it as a modulo 256 value. In other words, 
VAX BASIC treats the integer expression as the remainder of the actual 
supplied integer divided by 256. Therefore, CHR$(325) is equivalent to 
CHR$(69) and CHR§(-1) is equivalent to CHR$(255). 


The following program outputs the character whose ASCII value corre- 
sponds to the input value modulo 256: 


Example 


PRINT “THIS PROGRAM FINDS THE CHARACTER WHOSE" 
PRINT "VALUE (MODULO 256) YOU TYPE" 

INPUT value% 

PRINT CHR$(value%) 

END 


Output 1 


THIS PROGRAM FINDS THE CHARACTER WHOSE 
VALUE (MODULO 256) YOU TYPE 

? 69 
E 


Output 2 


THIS PROGRAM FINDS THE CHARACTER WHOSE 
VALUE (MODULO 256) YOU TYPE 

? 1093 
E 


12.1.3 String Numeric Functions 


Numeric strings are numbers represented by ASCII characters. A numeric 
string consists of an optional sign, a string of digits, and an optional 
decimal point. You can use E notation in a numeric string for floating- 
point constants. 


The following sections describe some of the VAX BASIC numeric string 
functions. 


12.1.3.1 The FORMATS Function 


The FORMATS function converts a numeric value to a string. The output 
string is formatted according to a string you provide. The expression 
you give this function can be any string or numeric expression. The 
format string must contain at least one PRINT USING format field. The 
formatting rules are the same as those for printing numbers with PRINT 
USING. See Chapter 16 in this manual for more information on the 
PRINT USING statement and formatting rules. 


Example 


A=5 

BS = "##.##" 

Z$ = FORMAT$(A, B$) 
PRINT 2$ 

END 


Output 
5.00 


12.1.3.2 The NUM§$ and NUM1$§$ Functions 


The NUM$ function evaluates a numeric expression and returns a string 
of characters formatted as the PRINT statement would format it. The 
returned numeric string is preceded by one space for positive numbers 
and by a minus sign for negative numbers. The numeric string is always 
followed by a space, as shown in the following example. 
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Example 


PRINT NUM$(7465097802134) 
PRINT NUM$(-50) 
END 


Output 


- 74651E+13 
-50 


The NUM1$§ function translates a number into a string of numeric charac- 
ters. NUM1$ does not return leading or trailing spaces or E format. The 
following example illustrates the use of the NUM1$ function: 


Example 


PRINT NUMi$(PI) 

PRINT NUM1$(97.5 * 30456.23 + 30385.1) 
PRINT NUM1$(1E-38) 

END 


Output 


3.14159 
2999870 
.00000000000000000000000000000000000001 


NUM1§ returns up to 6 digits of accuracy for single-precision real num- 
bers, up to 16 digits of accuracy for double-precision numbers, and up to 
10 digits of accuracy for LONG integers. NUM1§ returns up to 15 digits 
of accuracy for GFLOAT numbers and up to 33 digits of accuracy for 
HFLOAT numbers. 


The following example shows the difference between NUM$ and NUM1$: 


Example 
A$ = NUM$(1000000) 
B$ = NUM1$(1000000) 


PRINT LEN(A$); "/"; A$; "/" 
PRINT LEN(B$); "/"; BS; "/" 
END 


Output 


8 / .1E+07 / 
7 /1000000/ 


Note that A$ has a leading and trailing space. 


12.1.3.3 The VAL% and VAL Functions 


The VAL% function returns the integer value of a numeric string. This 
numeric string expression must be the string representation of an integer. 
It can contain the ASCII characters 0 through 9, a plus sign (+), and a 
minus sign (-). 


The VAL function returns the floating-point value of a numeric string. 
The numeric string expression must be the string representation of some 
number. It can contain the ASCII characters 0 through 9, a plus sign (+), 
a minus sign (-), and an uppercase E. 


VAL returns a number of the default floating-point data type. VAX BASIC 
signals “Illegal number” (ERR = 52) if the argument is outside the range of 
the default floating-point data type. 


The following is an example of VAL and VAL%: 


Example 

A = VAL("922") 
B$ = "100" 

C% = VALY,(B$) 
PRINT A 

PRINT C% 

END 


Output 


922 
100 


12.1.4 String Arithmetic Functions 


String arithmetic functions process numeric strings as arithmetic operands. 
This lets you add (SUM$), subtract (DIF$), multiply (PROD$) and divide 
(QUO$) numeric strings, and express them at a specified level of precision 
(PLACES). 


String arithmetic offers greater precision than floating-point arithmetic or 
longword integers, and it eliminates the need for scaling. However, string 
arithmetic executes much more slowly than the corresponding integer or 
floating-point operations. 
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The operands for the functions can be numeric strings representing any 
integer or floating-point value (E notation is not valid). Table 12-1 
shows the string arithmetic functions and their formats, and gives brief 
descriptions of what they do. 


Table 12-1: String Arithmetic Functions 


Function Format Description 
SUM$ SUM$(A$,B$) B$ is added to A§. 
DIF$ DIF$(A$,B$) B$ is subtracted from A$. 


PROD$ PROD$(A$,B$,P%) A$ is multiplied by B$. The product is 
expressed with precision P%. 


QUO$ QUOS$(A$,B$,P%) A$ is divided by B$. The quotient is ex- 
pressed with precision P%. 
PLACE$ PLACE$(A$,P%) A$ is expressed with precision P%. 


String arithmetic computations permit 56 significant digits. The functions 

QUO$, PLACE$, and PROD$, however, permit up to 60 significant digits. 
Table 12-2 shows how VAX BASIC determines the precision permitted by 
each function and if that precision is implicit or explicit. 


Table 12-2: Precision of String Arithmetic Functions 


Function How Determined How Stated 
SUM$ Precision of argument Implicitly 
DIF$ Precision of argument Implicitly 
PROD$ Value of argument Explicitly 
QUO$ Value of argument Explicitly 
PLACE$ Value of argument Explicitly 


12.1.4.1 The SUMS$§ and DIF$ Functions 


SUM$ and DIF$ take the precision of the more precise argument in the 
function unless padded zeros generate that precision. SUM$ and DIF$ 
omit trailing zeros to the right of the decimal point. 
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The size and precision of results returned by the SUM$ and DIF$ functions 
depend on the size and precision of the arguments involved: 


The sum or difference of two integers takes the precision of the larger 
integer. 


The sum or difference of two decimal fractions takes the precision of 
the more precise fraction. 


The sum or difference of two real numbers takes precision as follows: 


— The sum or difference of the integer parts takes the precision of 
the larger part. 


— The sum or difference of the decimal fraction parts takes the 
precision of the more precise part. 


VAX BASIC truncates trailing zeros. 


12.1.4.2 The QUO$S, PLACES, and PROD$ Functions 


In the PLACE$, PROD$, and QUO$ functions, the value of the integer 
expression argument explicitly determines numeric precision. That is, the 
integer expression parameter determines the point at which the number is 
rounded or truncated. 


If the integer expression is between -5000 and 5000, rounding occurs 
according to the following rules: 


For positive integer expressions, rounding occurs to the right of the 
decimal place. For example, if the integer expression is 1, rounding 
occurs one digit to the right of the decimal place (the number is 
rounded to the nearest tenth). If 2, rounding occurs two digits to 
the right of the decimal place (the number is rounded to the nearest 
hundredth), and 

so on. 


For zero, VAX BASIC rounds to the nearest unit. 


For negative integer expressions, rounding occurs to the left of the 
decimal place. For example, if the integer expression is -1, rounding 
occurs one place to the left of the decimal point. In this case, VAX 
BASIC moves the decimal point one place to the left, then rounds to 
units. If the integer expression is -2, rounding occurs two places to the 
left of the decimal point; VAX BASIC moves the decimal point two 
places to the left, then rounds to units. 


Note that when rounding numeric strings, VAX BASIC returns only part 
of the number. 
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If the integer expression is between 5001 and 15000, the following rules 
apply: 


e If the integer expression is 10000, VAX BASIC truncates the number at 
the decimal point. 


e If the integer expression is greater than 10000 (10000 plus n) VAX 
BASIC truncates the numeric string n places to the right of the decimal 
point. For example, if the integer expression is 10001 (10000 plus 1), 
VAX BASIC truncates the number starting one place to the right of 
the decimal point. If 10002 (10000 plus 2), VAX BASIC truncates the 
number starting two places to the right of the decimal point, and 
so on. 


e If the integer expression is less than 10000 (10000 minus n) VAX 
BASIC truncates the numeric string 1 places to the left of the decimal 
point. For example, if the integer expression is 9999 (10000 minus 1), 
VAX BASIC truncates the number starting one place to the left of the 
decimal point. If 9998 (10000 minus 2), VAX BASIC truncates starting 
two places to the left of the decimal point, and so on. 


The PLACE$ function returns a numeric string, truncated or rounded 
according to an integer argument you supply. 


The following example displays the use of the PLACE$ function with 
several different integer expression arguments: 


Example 


number$ = "123456.654321" 
FOR I% = -5% TO 5% 

PRINT PLACE$(number$, I%) 
NEXT I% 
PRINT 
FOR I% = 9995 TO 10005 

PRINT PLACE$(number$, I%) 
NEXT I% 


Output 


1 

12 

123 

1235 

12346 
123457 
123456.7 
123456 .65 
123456 .654 
123456 .6543 
123456 .65432 


1 

12 

123 

1234 

12345 
123456 
123456 .6 
123456 .65 
123456 .654 
123456 .6543 
123456 .65432 


The PROD$ function returns the product of two numeric strings. The 
returned string’s precision depends on the value you specify for the 
integer precision expression. (See Section 12.1.4 for allowable values of 
the integer precision expression). 


Example 
AS = "-4.333" 
B$ = "7.23326" 


s_product$ = PROD$(A$, B$, 10005%) 
PRINT s_product$ 
END 


Output 
-31.34171 


12.1.5 Date and Time Functions 


VAX BASIC supplies functions to return the date and time in numeric or 
string format. The following sections discuss these functions. 


Note that you can also use certain system services and Run-Time 
Library routines for more sophisticated date and time functions. See the 
VAX/VMS System Services Reference Manual and the VAX/VMS Run-Time 
Library Routines Reference Manual for more information. 
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12.1.5.1 The DATE$ Function 


The DATE$ function returns a string containing a day, month, and year in 
the form dd-Mmm-yy. The date integer argument to the DATE$ function 
can have up to six digits in the form yyyddd, where yyy specifies the 
number of years since 1970 and ddd specifies the day of that year. If the 
numeric expression is zero, DATE$ returns the current date. 


Example 


PRINT DATE$(0) 
PRINT DATE$(126) 
PRINT DATE$(6168) 
END 


Output 


15-Jun-85 
06-May-70 


' 16-Jun-76 


If you supply an invalid date (for example, day 370 of 1973), the results 
are undefined. 


12.1.5.2 The TIMES Function 
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The TIMES function returns a string displaying the time of day in the form 
hh:mm AM or hh:mm PM. TIME$ returns the time of day at a specified 
number of minutes before midnight. If you specify zero in the numeric 
expression, TIME$ returns the current time of day. 


Example 


PRINT TIME$(0) 
PRINT TIME$(1) 
PRINT TIME$(1440) 
PRINT TIME$(721) 
END 


Output 


03:53 PM 
11:59 PM 
12:00 AM 
11:59 AM 


12.1.5.3 The TIME Function 


The TIME function requests time and usage information from the operat- 
ing system and returns it to your program. The information returned by 
the TIME function depends on the value of the argument passed to it. The 
values and the information they return are listed below: 


0 Returns the number of seconds elapsed since midnight 

1 Returns the current job’s CPU time in tenths of a second 
2 Returns the current job’s connect time in seconds 

3 Returns zero 

4 Returns zero 


All other arguments to TIME are undefined and cause VAX BASIC to 
signal “Not implemented” (ERR=250). 


12.1.6 Terminal Control Functions 


VAX BASIC provides several terminal control functions. These functions 
let you: 


e Enable and disable CTRL/C trapping 
e Enable and disable terminal echoing 
¢ Read a single keystroke from a terminal 


12.1.6.1 The CTRLC and RCTRLC Functions 


The CTRLC function enables CTRL/C trapping, and the RCTRLC function 
disables CTRL/C trapping. When CTRL/C trapping is enabled, control is 
transferred to the program’s error handler when a CTRL/C is detected at 
the controlling terminal. 


CTRL/C trapping is asynchronous. The trap can occur in the middle of an 
executing statement, and a statement so interrupted leaves variables in an 
undefined state. For example, the statement A$ = “ABC”, if interrupted by 
CTRL/C, could leave the variable A$ partially set to “ABC” and partially 
left with its old contents. 


For example, if you type a CTRL/C to the following program when 
CTRL/C trapping is enabled, an “ABORT” message prints to the file open 
on channel #1. This lets you know that the program did not end correctly. 
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Example 


WHEN ERROR USE error_handler 
Y% = CTRLC 


END WHEN 
HANDLER error_handler 
IF ERR = 28 THEN PRINT #1%, "Abort" 


END HANDLER 


NOTE 


When you trap a CTRL/C with an error handler, your program 
may be in an inconsistent state; therefore, you should handle 
the CTRL/C error and exit the program as quickly as possible. 


12.1.6.2 The ECHO and NOECHO Functions 
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The NOECHO function disables echoing on a specified channel. Echoing 
is the process by which characters typed at the terminal keyboard appear 
on the screen. 


If you specify channel #0 (your terminal) as the argument, the characters 
typed on the keyboard are still accepted as input; however, they do not 
appear on the screen. 


The ECHO function enables echoing on a specified channel and cancels 
the effect of the NOECHO function on that channel. 


If you do not use these functions, ECHO is the default. This program 
shows a password routine in which the password does not echo: 


Example 


Y% = NOECHO(0%) 

INPUT "PASSWORD"; pword$ 

IF pword$=="PLUGH" THEN PRINT “THAT IS CORRECT" 
END IF 

Y% = ECHO(0%) 

END 


Note that the Y% = ECHO(0%) statement is necessary to turn the echo 
back on. If this statement were not included, then all subsequent user 
inputs would not echo to the terminal screen. 


12.1.6.3 The INKEY$ Function 


The INKEY$ function reads a single keystroke from a terminal opened on 
a specified channel and returns the typed character. 


If you specify a channel that is not open, VAX BASIC signals the error 
“I/O channel not open” (ERR=9). If a file or a device other than a terminal 
is open on the channel, VAX BASIC signals the error “Illegal operation” 
(ERR=141). 


Once you have specified a channel, VAX BASIC allows you to specify an 
optional WAIT clause. A WAIT clause followed by no value tells VAX 
BASIC to wait indefinitely for input to become available. A WAIT clause 
followed by a value from 1 through 255 tells VAX BASIC to wait the 
specified number of seconds for input. 


Example 


DECLARE STRING KEYSTROKE 
Inkey_Loop: 
WHILE 1% 

KEYSTROKE = INKEY$(1%, WAIT) 


SELECT KEYSTROKE 
CASE '26'C 
PRINT "CTRL/Z to exit" 
EXIT Inkey_Loop 
CASE CR,LF,VT,FF,ESC 
PRINT "Line terminator" 
CASE "PF1i" TO “PF4" 
PRINT "P key" 
CASE "Ei" TO "E6" 
PRINT "VT200 Function key" 
CASE "KPO" TO "KP9" 
PRINT "Application keypad key" 
CASE < SP 
PRINT "Control character" 
CASE '127'C 
PRINT "<DEL>" 
CASE ELSE 
PRINT "Character is "; KEYSTROKE 
END SELECT 
NEXT 
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12.2 User-Defined Functions 
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The DEF statement lets you create your own single-line or multi-line 
functions. 


In the traditional VAX BASIC usage, a function name consists of the 
following: 


e The letters FN 
¢ From 1 to 28 letters, digits, underscores, or periods 
e An optional percent sign or dollar sign 


Integer function names must end with a percent sign and string function 
names must end with a dollar sign. Therefore, the function name can 
have up to 31 characters. If the function name ends with neither a percent 
sign nor a dollar sign, the function returns a real number. 


You can create user-defined functions using these function naming rules. 
However, DIGITAL recommends that you use explicit data typing when 
defining functions for new program development. Refer to Chapter 14 
for an example of an explicitly declared function. Note that the function 
name must start with FN only if the function is not explicitly declared and 
a function reference lexically precedes the function definition. 


DEF functions can be either single-line or multi-line. Whether you use 
the single-line or multi-line format for function definitions depends on 
the complexity of the function you create. In general, multi-line DEF 
functions perform more complex functions than single-line DEF functions. 
However, the important distinction between single- and multi-line DEF 
functions is that multi-line DEF functions can be invoked recursively, 
whereas single-line DEF functions cannot. 


If you want to pass values to a function, the function definition requires a 
formal parameter list. These formal parameters are the variables used to 
calculate the value returned by the function. When you invoke a function, 
you supply an actual parameter list; the values in the actual parameter list 
are copied into the formal parameter at this time. DEF functions allow up 
to eight formal parameters. You can specify variables, constants, or array 
elements as formal parameters, but you cannot specify an entire array as a 
parameter to a DEF function. 


12.2.1 Single-Line DEF Functions 


In a single-line DEF, the function name, the formal parameter list, and the 
defining expression all appear on the same line. The defining expression 
specifies the calculations that the function performs. You can pass up to 
eight arguments to this function through the formal parameter list. These 
parameters are variables local to the function definition, and each formal 
parameter can be preceded by a data type keyword. 


The following example creates a function named fnratio. This function has 
two formal parameters: numer and denomin, whose ratio is returned as a 
REAL value. 


When the function is invoked, VAX BASIC does the following: 


¢ Copies the values 5.6 and 7.8 into the formal parameters numer and 
denomin 


¢ Evaluates the expression to the right of the equal sign 

e Returns the value to the statement that invoked the function (the 
PRINT statement) 

The PRINT statement then prints the returned value. 


Example 
DEF REAL fnratio (numer, denomin) = numer / denomin 


PRINT fnratio(5.6, 7.8) 
END 


Output 
.717949 


Note that the actual parameters you supply must agree in number and 
data type with those in the formal parameter list; you must supply 
numeric values for numeric variables, and string values for string variables. 


The defining expression for a single-line function definition can contain 
any constant, variable, VAX BASIC built-in function, or any user-defined 
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function except the function being defined. The following are valid 
function definitions: 


Example 


DEF FN_A(X) = X°2+3+*X+4 

DEF FN_B(X) = FN_A(X) / 2 + FN_A(X) 
DEF FN_C(X) = SQR(X+4) + 1 

DEF CUBE(X) = X ~*~ 3 


Note that the name of the last function defined does not begin with FN. 
This is valid as long as no reference to the function lexically precedes the 
function definition. 


You can also define a function that has no formal parameters. For in- 
stance, the following function definition uses three VAX BASIC built-in 
functions to return an integer corresponding to the day of the month. 
DATE§(0) returns a date string in the form dd-Mmm-yy. The SEG$ func- 
tion strips out of this value the characters starting at character position 

1 up to and including the character at position 2 (the day number). The 
VAL% function converts this resulting numeric string to an integer. In this 
way, fnday_number returns the day of the month as an integer. 


DEF INTEGER fnday_number = VAL% (SEG$(DATE$(0%), 1%, 2%)) 


12.2.2 Multi-Line DEF Functions 
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The DEF statement can also define multi-line functions. Multi-line DEF 
functions are useful for expressing complicated functions. Note that multi- 
line DEF functions do not have the equal sign and defining expression 

on the first line. Instead, this expression appears in the function block, 
assigned to the function name. 


NOTE 


If a multi-line DEF function contains DATA statements, they are 
global to the program. 


Multi-line function definitions can contain any constant, variable, VAX 
BASIC built-in function, or user-defined function. In VAX BASIC, the 
function definition can contain a reference to the function you are defining. 
Therefore, a multi-line DEF function can be recursive, or invoke itself. 


You can use either the END DEF or EXIT DEF statements to exit from 
a user-defined function. The EXIT DEF statement is equivalent to an 
unconditional transfer to the END DEF statement. 


The following example shows a multi-line DEF function that uses both the 
EXIT and END DEF statements. The defining expression of the function 
is in the ELSE clause. This assigns a value to the function if A is less 
than 10. The second set of output shows what happens when A is greater 
than 10; VAX BASIC prints “OUT OF RANGE” and executes the EXIT 
DEF statement. The function returns zero because control is transferred 
to the END DEF statement before a value was assigned. In this way, this 
example tests the arguments before the function is evaluated. 


Example 


DEF fn_discount (A) 
IF A> 10 
THEN 
PRINT "OUT OF RANGE" 
EXIT DEF 
ELSE 
fn_discount = A*A 
END IF 
END DEF 


INPUT Z 
PRINT fn_discount(Z) 
END 


Output 1 


74 
256 


Output 2 


? 12 
OUT OF RANGE 
.¢) 


If you do not explicitly declare the function with the DECLARE statement, 
the restrictions for naming a multi-line DEF function are the same as those 
for the single-line DEF function. However, explicitly declaring a DEF 
function can make a program easier to read and understand. For instance, 
Example 1 concatenates two strings and Example 2 returns a number in a 
specified modulus. 
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Example 1 
DECLARE STRING FUNCTION concat (STRING, STRING) !Declare the function 


DEF STRING concat (STRING Y, STRING Z) 
concat = Y + Z !Define the function 
FNEND 


new_string$ = concat(A$, B$) !Invoke the function 


END 


Example 2 


DECLARE REAL FUNCTION mdlo (REAL, INTEGER) 
DEF mdlo( REAL argument, INTEGER modulus ) 


!Check for argument equal to zero 


EXIT DEF IF argument = 0 


!Check for modulus equal to zero, modulus equal to absolute 
!value of argument, and modulus greater than absolute 
!value of argument. 


SELECT modulus 

CASE = 0% 
EXIT DEF 

CASE > ABS( argument ) 
EXIT DEF 

CASE = ABS( argument ) 
mdlo = argument 
EXIT DEF 

END SELECT 


!If argument is negative, set flag negative, and set argument 
!to its absolute value. 


IF argument < 0 
THEN argument = ABS( argument ) 
negative, = -1% 
END IF 


UNTIL argument < modulus 
argument = argument - modulus 
{If this calculation ever results in zero, mdlo returns zero 


IF argument = modulus 
THEN mdlo = 0 
EXIT DEF 
END IF 
NEXT 


!Argument now contains the right number, but the sign may be wrong. 
!If the negative argument flag was set, make the result negative. 


IF negative’ 


THEN mdlo = - argument 
ELSE mdlo = argument 
END IF 
END DEF 


INPUT “PLEASE INPUT THE VALUE AND THE MODULUS"; X,Y 
PRINT mdlo(X,Y) 
END 


Output 


PLEASE INPUT THE VALUE AND THE MODULUS? 7, 5 
2 


Because these functions are declared in DECLARE statements, the function 
names do not have to conform to the traditional VAX BASIC rules for 
naming functions. 


Recursion occurs when a function calls itself. The following example 
defines a recursive function that returns a number’s factorial value. 
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Example 


DECLARE INTEGER FUNCTION factor ( INTEGER ) 
DEF INTEGER factor ( INTEGER F ) 
IF F <= 0% 
THEN factor = 1% 
ELSE factor = factor(F - 1%) * F 
END IF 
END DEF 
INPUT "INPUT N TO FIND N FACTORIAL"; NY% 
PRINT "N! IS"; factor(N%) 
END 


Output 


INPUT N TO FIND N FACTORIAL? 5 
N! IS 120 


Any variable accessed or declared in the DEF function and not in the 

formal parameter list is global to the program unit. When VAX BASIC 
evaluates the user-defined function, these global variables contain the 

values last assigned to them in the surrounding program module. 


To prevent confusion, variables declared in the formal parameter list 
should not appear elsewhere in the program. Note that if your function 
definition actually uses global variables, these variables cannot appear in 
the formal parameter list. 


You cannot transfer control into a multi-line DEF function except by 
invoking it. You should not transfer control out of a DEF function except 
by way of an EXIT DEF or END DEF statement. This means that: 


e If the DEF function contains an ON ERROR GOTO, GOTO, ON 
GOTO, GOSUB, ON GOSUB, or RESUME statement, that statement’s 
target line number must also be in that DEF function. 


e An ON ERROR GO BACK statement can transfer control out of a DEF 
function; however, a RESUME statement in an error handler outside 
the DEF function cannot transfer control back into the DEF function. 


e If the DEF function contains a handler, and was invoked from a 
protected region, an EXIT HANDLER statement causes control to 
be transferred to the specified handler for that protected region. 
However, if the DEF function contains a handler but was not invoked 
from a protected region, an EXIT HANDLER statement causes control 
to be transferred to the default error handler. 


e A subroutine cannot be shared by more than one DEF function. 
However, if you rewrite the subroutine as a DEF function with no 
parameters, other function definitions can share it. 


A DEF function never changes the value of a parameter passed to it. Also, 
because formal parameters are local to the function definition, you cannot 
access the values of these variables from outside the DEF statement. These 
variable names are known only inside the DEF statement. 


In the following example, the variable first is declared only in the function 
fn_sum. When VAX BASIC sees the second PRINT statement, it assumes 
that first is a new variable that is not declared in the main program. If you 
try to run this example, VAX BASIC signals the error “explicit declaration 
of first required”. If you do not specify the OPTION TYPE = EXPLICIT 
statement, VAX BASIC assumes that first is a new variable and initializes 
it to zero. 


Example 


OPTION TYPE = EXPLICIT 

DECLARE INTEGER A, B 

DEF fn_sum(INTEGER first, INTEGER second) = first + second 
A = 50 

B = 25 

PRINT fn_sum(A, B) 

PRINT first 

END 
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Chapter 13 


String Handling 


This chapter defines dynamic and fixed-length strings and string virtual 
arrays, explains which you should choose for your application, and shows 
you how to use them. 


13.1 Introduction 


A string is a sequence of ASCII characters. VAX BASIC allows you to use 
three types of strings: 


e Dynamic strings 
e Fixed-length strings 
¢ String virtual arrays 


Dynamic strings are strings whose length can change during program 
execution. The length of a dynamic string variable may or may not 
change, depending on the statement used to modify it. 


Fixed-length strings are strings whose length never changes. In other 
words, their length remains static. String constants are always fixed- 
length. String variables can be either fixed-length or dynamic. A string 
variable is fixed-length if it is named in a COMMON, MAP, or RECORD 
statement. If a string variable is not part of a map or common block, 
RECORD, or virtual array, it is a dynamic string. When a string variable 
is fixed-length, its length does not change, regardless of the statement 
you use to modify it. See Table 13-1 for more information on string 
modification. 
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Strings in virtual arrays have both fixed-length and dynamic attributes. 
String virtual arrays have a specified maximum length between 0 and 
512 characters. During program execution, the length of an element in a 
string virtual array can change; however, the length is always between 0 
and the maximum string size specified when the array was created. See 
Section 13.4 and Chapter 15 for more information about virtual arrays. 


Table 13-1: String Modification 


Changes made to Changes made to 
Statement Fixed-Length Strings Dynamic Strings 
LET Value Value and length 
LSET Value Value 
RSET Value Value 
Terminal I/O Value Value and length 


Statements! 


1 Terminal 1/O statements include INPUT, INPUT LINE, LINPUT, MAT INPUT, and so on. 


13.2 Using Dynamic Strings 


Although dynamic strings are less efficient than fixed-length strings, they 
are often more flexible. For example, to concatenate strings, you can just 
use the LET statement to assign the concatenated value to a dynamic string 
variable, without having to be concerned about VAX BASIC truncating the 
string or adding trailing spaces to it. However, if the destination variable 
is fixed-length, you must make sure that it is long enough to receive the 
concatenated string, or VAX BASIC truncates the new value to fit the 
destination string. Similarly, if you use LSET or RSET to concatenate 
strings, you must ensure that the destination variable is long enough to 
receive the data. 


The LET, LSET and RSET statements all operate on dynamic strings as 
well as fixed-length strings. The LET statement can change the length 

of a dynamic string; LSET and RSET do not. LSET and RSET are more 
efficient than LET when changing the value of a dynamic string. For more 
information on LSET and RSET, see Sections 13.5.2 and 13.5.3. 
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In the following example, the first line assigns the value “ABC” to A$, the 
second line assigns “XYZ” to B$, and the third line assigns six spaces to 
C$. These variables are dynamic strings. In the fourth line, LSET assigns 
A$ the value of A$ concatenated with B$. Because the LSET statement 
does not change the length of the destination string variable, only the first 
three characters of the expression A$ + B$ are assigned to A$. The fifth 
line uses LSET to assign C$ the value of A$ concatenated with B$. Because 
C$ already has a length of 6, this statement assigns the value “ABCXYZ” 
to it. 


Example 

LET A$ = "ABC" 
LET B$ = "XYZ" 
LET C$ =" " 


LSET A$ = A$ + BS 
LSET C$ = A$ + BS 
PRINT A$ 

PRINT C$ 

END 


Output 


ABC 
ABCXYZ 


Like the LET statement, the INPUT, INPUT LINE, and LINPUT statements 
can change the length of a dynamic string, but they cannot change the 
length of a fixed-length string. 


In this example, the first line assigns the null string to variable A$. The 
second line uses the LEN function to show that the null string has a length 
of zero. The third line uses the INPUT statement to assign a new value to 
A$, and the fourth and fifth lines print the new value and its length. 
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Example 


!'Declare a dynamic string 
LET A$ = "" 

PRINT LEN(A$) 

INPUT A$ 

PRINT A$ 

PRINT LEN(A$) 

END 


Output 


0 
? THIS IS A TEST 
THIS IS A TEST 
14 


You should not confuse the null string with a null character. A null 
character is one whose ASCII numeric code is zero. The null string is a 
string whose length is zero. 


13.3 Using Fixed-Length Strings 


It is generally more efficient to manipulate a fixed-length string than a 
dynamic string. Creating or modifying a dynamic string often causes 
VAX BASIC to create new storage, and this increases processor overhead. 
Modifying fixed-length strings involves less overhead because VAX BASIC 
manipulates existing storage using VAX character instructions. 


If a string variable is part of a map or common block, or virtual array, a 
LET, INPUT, LINPUT, or INPUT LINE statement changes its value, but 
not its length. In the following example, the MAP statement in the first 
line explicitly assigns a length to each string variable. Because the LINPUT 
statements cannot change this length, VAX BASIC truncates values to fit 
the address and city_state variables. Because the zip variable is longer than 
the assigned value, VAX BASIC left-justifies the assigned value and pads it 
with spaces. The sixth line uses the compile-time constant HT (horizontal 
tab) to separate fields in the employee record. 
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Example 


MAP (FIELDS) STRING full_name = 10, 
address = 10, 
city_state = 10, 
zip = 10 
LINPUT "NAME"; full_name 
LINPUT "ADDRESS"; address 
LINPUT "CITY AND STATE"; city_state 
LINPUT "ZIP CODE"; zip 
EMPLOYEE_RECORD$ = full_name + HT + address + HT & 
+ city_state + HT + zip 
PRINT EMPLOYEE_RECORD$ 
END 


& & & 


Output 


NAME? JOE SMITH 

ADDRESS? 66 GRANT AVENUE 
CITY AND STATE? NEW YORK NY 
ZIP? 01001 


JOE SMITH 66 GRANT A NEW YORK N 01001 


13.4 Using String Virtual Arrays 


Virtual arrays are stored on disk. You create a virtual array by opening a 
disk file and then using the DIM # statement to dimension the array on 
the open channel. This section describes only string virtual arrays. See 
Chapter 15 for more information on virtual arrays. 


Elements of string virtual arrays behave much like dynamic strings, with 
two exceptions: 


e When you create the virtual string array, you specify a maximum 
length for the array’s elements. The length of an array element can 
never exceed this maximum. If you do not supply a length, the default 
is 16 characters. 


¢ A string virtual array element cannot contain trailing nulls. 


When you assign a value to a string virtual array element, VAX BASIC 
pads the value with nulls, if necessary, to fit the length of the virtual array 
element. However, when you retrieve the virtual array element, VAX 
BASIC strips all trailing nulls from the string. Therefore, when you access 
an element in a string virtual array, the string never has trailing nulls. 
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In the following example, The first two lines dimension a string virtual 
array and open a file on channel #1. The third line assigns a 10-character 
string to the first element of this string array, and to the variable A$. This 
10-character string consists of “ABCDE” plus five null characters. The 
PRINT statements show that the length of A$ is 10, while the length of 
test(1) is only 5 because VAX BASIC strips trailing nulls from string array 
elements. 


Example 


DIM #1%, STRING test (5) 

OPEN "TEST" AS FILE #1%, ORGANIZATION VIRTUAL 
A$, test(1%) = "ABCDE" + STRING$(5%, 0%) 
PRINT "LENGTH OF A$ IS: "; LEN(A$) 

PRINT "LENGTH OF TEST(1) IS: "; LEN(test(1%)) 
END 


Output 


LENGTH OF A$ IS: 10 
LENGTH OF TEST(1) IS: 5 


Although the storage for string virtual array elements is fixed, the length 
of a string array element can change because VAX BASIC strips the trailing 
nulls whenever it retrieves a value from the array. 


13.5 Assigning String Data 


To assign string data, you use the LET, LSET, RSET, and MID$ statements. 
The following sections describe how to use these statements. 


13.5.1 The LET Statement 


The LET statement assigns string data to a string variable. The keyword 
LET is optional. Again, LSET is more efficient than LET when changing 
a dynamic string variable. In the following example, B is a string variable 
and “ret_status” is a quoted string expression. 


LET B = "ret_status" 
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The LET statement changes the length of dynamic strings but does not 
change the length of fixed-length strings. For instance, the following 
example, first creates a fixed-length string named ABC by declaring the 
string in a MAP statement. The program then creates a dynamic string 
named XYZ by declaring it in a DECLARE statement. The third line 
assigns a 3-character value to both variable ABC and XYZ, then prints 
the value and the length of the string variables. Variable ABC continues 
to have a length of 10: the three characters assigned, plus seven spaces 
for padding. The length of the dynamic variable changes with the values 
assigned to it. 


Example 


MAP (TEST) STRING ABC = 10 
DECLARE STRING XYZ 

ABC = "ABC" 

XYZ = "XYZ" 

PRINT ABC, LEN(ABC) 

PRINT XYZ, LEN(XYZ) 

ABC = "A" 

XYZ = "x" 

PRINT ABC, LEN(ABC) 

PRINT XYZ, LEN(XYZ) 


Output 

ABC 10 
XYZ 3 
A 10 
x 1 


13.5.2 The LSET Statement 


The LSET statement left-justifies data and assigns it to a string variable, 
without changing the variable’s length. In the following example, ABC is 
a string variable and “ABC” is a string constant. 


LSET ABC = "ABC" 


If the string expression’s value is shorter than the string variable’s current 
length, LSET left-justifies the expression and pads the string variable 
with spaces. In the following example, the LET statement creates the 
5-character string variable test$. The LSET statement in the second line 
assigns the string XYZ to the variable test$ but does not change the 
length of test$. Because test$ has a length of 5, the LSET statement pads 
the string XYZ with two spaces when assigning the value. The PRINT 
statement shows that test$ includes these two spaces. 
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Example 


LET test$ = "ABCDE" 
LSET test$ = "XYZ" 
PRINT "'"; test$; "'" 
END 


Output 
"XYZ = 


LSET left-justifies a string expression longer than the string variable and 
truncates it on the right as shown in the following example: 


Example 


LET test$ = "ABCDE" 
LSET test$ = "12345678" 
PRINT test$ 

END 


Output 
12345 


The LET statement creates the 5-character string variable test$. The 
LSET statement in the second line assigns the characters “12345” to test$. 
Because LSET does not change the string variable’s length, it truncates the 
last three characters (678). 


13.5.3 The RSET Statement 


The RSET statement right-justifies data and assigns it to a string variable 
without changing the variable’s length. In the following example, C_R is 
a string variable and “cust_rec” is a string constant. 


RSET C_R = "cust_rec" 


RSET right-justifies a string expression shorter than the string variable 
and pads it with spaces on the left. In the following example, the LET 
statement creates the 5-character string variable test$. The RSET statement 
in the second line assigns the string XYZ to test$ but does not change 

the length of test$. Because test$ is five characters long, the RSET state- 
ment pads XYZ with two spaces when assigning the value. The PRINT 
statement shows that test$ includes these two spaces. 
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Example 


LET test$ = "ABCDE" 
RSET test$ = "XYZ" 
PRINT "'" ; test$; "'" 
END 


Output 
‘xyz! 


If the string expression’s value is longer than the string variable, RSET 
right-justifies the string expression and truncates characters on the left to 
fit the string variable as shown in the following example: 


Example 


LET test$ = "ABCDE" 

RSET test$ = "987654321" 
PRINT test$ 

END 


Output 
54321 


The LET statement creates a 5-character string variable, test$. The RSET 
statement assigns “54321” to test$. RSET, which does not change the vari- 
able’s length, truncates “9876” from the left side of the string expression. 


Note that, when using LSET and RSET, padding can become part of the 
data: 

Example 

LET A$ = '12345' 

LSET A$ = ‘ABC! 

LET B$ = '12345678' 

RSET B$ = A$ 

PRINT win Bg, mis 

Output 


a 18 ABC ' 
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13.5.4 The MIDS Assignment Statement 


You can replace a portion of a string with another string using the MID$ 
assignment statement. You specify a starting character position that indi- 
cates where to begin the substitution. If you specify a starting character 
position that is less than 1, VAX BASIC assumes a starting character posi- 
tion of 1. In addition, you can optionally specify the number of characters 
to substitute from the source string expression. If you do not specify the 
number of characters to substitute, VAX BASIC attempts to insert the 
entire source expression. However, the MID$ statement never changes the 
length of the target string variable; therefore, the entire source expression 
may not fit into the available space. 


The following example illustrates the use of MID$ as an assignment 
statement. In this example, “ABCD” is the input string, the starting 
character position is 1, and the length of the segment to be replaced is 3 
characters. Note that when you use MID§ as an assignment statement, the 
length of the input string does not change. Therefore, the length of the 
result (“123D”), is equal to the length of the input string. 


Example 


DECLARE STRING old_string, replace_string 
old_string = "ABCD" 

replace_string = "123" 

PRINT old_string 

MID$(old_string,1,3) = replace_string 
PRINT old_string 


Output 


ABCD 
123D 


Keep these considerations in mind when you use the MID$ assignment 
statement: 


e The length argument is optional. If not specified, the number of char- 
acters replaced will be the minimum of the length of the replacement 
string and the length of the input string minus the starting position 
value. 


e If the length of the segment is less than or equal to zero, VAX BASIC 
assumes a length of zero. 


e The length of the input string does not change regardless of the value 
of the length of the segment. 
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13.6 Manipulating String Data with String Functions 


When used with the LET statement, VAX BASIC string functions let you 
manipulate and modify strings. These functions let you: 

e Determine the length of a string (LEN) 

e Search for the position of a set of characters in a string (POS) 

e Extract segments from a string (SEG$, MID$) 


e Create a string of any length, made up of any single character 
(STRINGS) | 


e Create a string of spaces (SPACE$) 
¢ Remove trailing spaces and tabs from a string (TRM$) 
e Edit a string (EDIT$) 


These functions are discussed in the following sections. See the VAX 
BASIC Reference Manual for more information about each string function. 


13.6.1. The LEN Function 


The LEN function returns the number of characters in a string as an 
integer value. For example: 


LEN (spec) 


Spec is a string expression. The length of the string expression includes 
leading and trailing blanks. In the following example, the variable Z$ is 
set equal to “ABC XYZ”, which has a length of eight. 


Example 


alpha$ = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
PRINT LEN(alpha$) 

Z$ = *ABC" > Le 9 nunxyyzt 

PRINT LEN(Z$) 

END 


Output 


26 
8 
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13.6.2 The POS Function 


POS searches a string for a group of characters (a substring). In the 
following example, spec is the string to be searched, test is the substring 
for which you are searching and 15 is the character position where VAX 
BASIC starts the search. 


POS (spec, test ,15) 


The position returned by POS is relative to the beginning of the string, not 
the starting position of the search. For example, if you search the string 
“ABCDE” for the substring “E”, it does not matter whether you specify a 
starting position of 1, 2, 3, 4, or 5, VAX BASIC still returns the value 5 as 
the position where the substring was found. 


If the function finds the substring, it returns the position of the substring’s 
first character. Otherwise, it returns zero as in the following example: 


Example 


alpha$ = "ABCDEFGHI JKLMNOPQRSTUVWXYZ" 
Z$ = "DEFG" 

X% = POS(ALPHAS, Z$, 1%) 

PRINT X% 

Q$ = "TEST" 

Y% = POS(ALPHA$, Q$, 1%) 

PRINT Y% 

END 


Output 


4 
0 


If you specify a starting position other than 1, VAX BASIC still returns the 
position of the substring relative to the beginning of the string as shown 
in the following example: 

Example 

alpha$ = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

z$ = "HIS" 

PRINT POS(ALPHA$, Z$, 7%) 

END 

Output 


8 
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If you know that the substring is not near the string’s beginning, spec- 
ifying a starting position greater than one speeds program execution by 
reducing the number of characters VAX BASIC must search. 


You can use the POS function to associate a character string with an 
integer that you can then use in calculations. This technique is called a 
table lookup. For instance, the following example prompts for a 
3-character string, changes the string to uppercase letters and searches 
the table string to find a match. The WHILE loop executes indefinitely 
until a carriage return is typed in response to the prompt. 


Example 


DECLARE STRING CONSTANT table = & 
" JANFEBMARAPRMAY JUN JULAUGSEPOCTNOVDEC" 
DECLARE STRING month, UPPER_CASE_MONTH, message 
DECLARE INTEGER month_length 
DECLARE REAL month_pos 


PRINT "Please type the first three letters of a month" 
PRINT "To end the program, type only RETURN) ;" 
Loop_i: 
WHILE 1% = 1% 
INPUT month 
UPPER_CASE_MONTH = EDIT$(month, 32%) 
month_length = LEN (UPPER_CASE_MONTH) 
EXIT Loop_i IF month_length = 0% 
IF month_length = 3% 
THEN month_pos = (POS(table, UPPER_CASE_MONTH, 1) + 2) / 3 
IF (month_pos = 0%) OR (month_pos <> FIX(month_pos)) 


THEN MESSAGE = " Invalid abbreviation, try again" 
ELSE MESSAGE = " is month number" + NUM$(MONTH_POS) 
END IF 
ELSE MESSAGE = " Abbreviation not three characters, try again" 
END IF 
PRINT month; message 
NEXT 
END 
Output 


Please type the first three letters of a month 
To end the program, type only RETURN? Nov 
Nov is month number 11 


Keep these considerations in mind when you use POS: 


e If you specify a starting position less than 1, POS assumes a starting 
position of one. 


e If you specify a starting position greater than the searched string’s 
length, POS returns a zero (unless the substring is null). 
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¢ When searching for a null string: 


— If you specify a starting position greater than the string’s length, 
POS returns the string’s length plus one. 


— If the string to be searched is also null, POS returns a value of 
one. 

— If the specified starting position is less than or equal to 1, POS 
returns a value of one. 


— If the specified starting position is greater than one and less than 
or equal to the string’s length plus 1, POS returns the specified 
starting position. 


Note that searching for a null string is not the same as searching for the 
null character. A null string has a length of zero, while the null character 
has a length of one. The null character is an ASCII character whose value 
is zero. 


13.6.3 The SEGS Function 


The SEG$ function extracts a segment (substring) from a string. The 
original string remains unchanged. In the following example, time is the 
input string, 13 is the position of the first character extracted and 16 is the 
position of the last character extracted. 


SEG$ (time ,13,16) 


SEG$ extracts from the input string the substring that starts at the first 
character position, up to and including the last character position. It 
returns the extracted segment. 

Example 


PRINT SEG$("ABCDEFG", 3%, 5%) 
END 


Output 
CDE 


If you specify character positions that exist in the string, the length of the 
returned substring always equals (int-exp2 - int-exp1 + 1). 
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Keep these considerations in mind when you use SEG$: 


e If the starting character position is less than 1, VAX BASIC assumes a 
value of 1. 


e If the starting character position is greater than the ending character 
position, or the length of the string, SEG$ returns a null string. 


e If the ending character position is greater than the length of the string, 
SEG$ returns all characters from the starting character position to the 
end of the string. 


e If the starting character position is equal to the ending character 
position, SEG$ returns the character at the starting position. 


You can replace part of a string by using the SEG$ function with the string 
concatenation operator (+). In the following example, when VAX BASIC 
creates C$, it concatenates the first two characters of A$, the 3-letter string 
XYZ, and the last two characters of A$. The original contents of A$ do not 
change. 


Example 


A$ = "ABCDEFG" 

C$ = SEGS(A$, 1%, 2%) + "XYZ" + SEG$(A$, 6%, 7%) 
PRINT C$ 

PRINT A$ 

END 


Output 

ABXYZFG 

ABCDEFG 

You can use similar string expressions to replace characters in any string. 
If you do not change the length of the target string, use the MID$ as- 
signment statement to perform string replacement. A general formula to 


replace characters in positions n through m of string A$ with characters in 
B$ is: 


C$ = SEG$(A$,1%,n-1) + B$ + SEG$(A$,m+1,LEN(A$)) 


The following example replaces the sixth through ninth characters of the 
string “ABCDEFGHJK’ with “123456”. 
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Example 


A$ = “ABCDEFGHIJK" 
B$ = "123456" 

C$ = SEG$(A$,1%,5%) + B$ + SEG$(A$, 10%, LEN(A$)) 
PRINT C$ 

PRINT A$ 

PRINT B$ 

END 

Output 


ABCDE123456JK 
ABCDEFGHI JK 
123456 


The following formulas are more specific applications of the general 
formula. 


¢ To replace the first n characters of A$ with B$ use 
C$ = B$ + SEG$(A$,n+1,LEN(A$)) 

¢ To replace all but the first n characters of A$ with B$ use 
C$ = SEG$(A$,1,n) + BS 

e To replace all but the last n characters of A$ with B$ use 
C$ = B$ + SEG$(A$,(LEN(A$)-n) + 1,LEN(A$)) 

e To replace the last n characters of A$ with B$ use 
C$ = SEG$(A$,1,LEN(A$)—n) + BS 

e To insert B$ in A$ after the nth character in A$ use 


C$ = SEG$(A$,1,n) + B$ + SEG$(A$,n+1,LEN(A$)) 


13.6.4 The MIDS Function 


The MID$ function extracts a specified substring, beginning at a specified 
character position and ending at a specified length. If you specify a 
starting character position that is less than 1, VAX BASIC automatically 
assumes a starting character position of 1. 


In the following example, the MID$ function uses the input string 
“ABCD”, and extracts a segment consisting of 3 characters. Because 

VAX BASIC automatically assumes a starting character position of 1 when 
the specified starting character position is less than 1, the string that is 
extracted begins with the first character of the input string. 
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Example 


DECLARE STRING old_string, new_string 
old_string = "ABCD" 

new_string = MID$(old_string, 0, 3) 
PRINT new_string 


Output 

ABC 

Keep these considerations in mind when you use the MID$ function: 

e If the position of the segment’s first character is greater than the input 
string, MID$ returns a null string. 


e If the length of the segment is greater than the length of the input 
string, VAX BASIC returns the string that begins at the specified 
starting character position and includes all characters remaining in the 
string. 

e If the length of the segment is less than or equal to zero, MID$ returns 
a null string. 


e If you specify a floating-point expression for the position of the 
segment’s first character or for the length of the segment, VAX BASIC 
truncates it to a long integer. 


13.6.5 The STRINGS Function 


The STRINGS function creates a character string containing multiple 
occurrences of a single character. In the following example, 23 is the 
length of the returned string and 30 is the ASCII value of the character 
that makes up the string. This value is treated modulo 256. 


STRING$ (23, 30) 


The following example creates a 10-character string containing uppercase 
As, which have ASCII value 65. 
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Example 


out$ = STRING$(10%, 65%) 
PRINT out$ 

END 

Output 


AAAAAAAAAA 
Keep these considerations in mind when you use the STRING$ function: 


e If the length of the returned string is less than or equal to zero, 
STRING$ returns a null string. 


e If the length of the returned string is greater than 65535, VAX BASIC 
signals an error. 


13.6.6 The SPACES Function 
The SPACE$ function creates a character string containing spaces. In this 
example, 5 is the number of spaces in the string. 
SPACE$(5) 
The following example creates a 9-character string which contains 3 
spaces. 
Example 
A$ "ABC" 
BS = "XYZ" 


PRINT A$ + SPACE$(3%) + BS 
END 


Output 
ABC XYZ 


13.6.7. The TRMS Function 


The TRM$ function removes trailing blanks and tabs from a string. The 
input string remains unchanged. In the following example, all trailing 
blanks that appear in the string expression, “ABCDE ” are removed once 
the TRM$ function is invoked. 
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Example 


A$ = "ABCDE 7 
B$ = "XYZ" 

first$ = A$ + B$ 
second$ = TRM$(A$) + B$ 
PRINT first$ 

PRINT second$ 

END 


Output 


ABCDE XYZ 
ABCDEXYZ 


The TRM$ function is especially useful for extracting the nonblank char- 
acters from a fixed-length string (for example, a COMMON or MAP, or a 
parameter passed from a program written in another language). 


13.6.8 The EDITS Function 


The EDIT$ function performs one or more string editing functions, de- 
pending on the value of an argument you supply. The input string 
remains unchanged. In the following example, stu_rec is a string expres- 
sion and 32 determines the editing function performed. 


EDIT$(stu_rec , 32) 


Table 13-2 shows the action VAX BASIC takes for a given value of the 
integer expression. 


Table 13-2: EDITS Options 


Value of 

Expression Effect 

1 Discards each character’s parity bit (bit 7). Note that you should 
not use this value for characters in the DEC Multinational 
Character Set. 

2 Discards all spaces and tabs. 

4 Discards all carriage returns, line feeds, form feeds, deletes, 
escapes, and nulls. 

8 Discards leading spaces and tabs. 

16 Converts multiple spaces and tabs to a single space. 
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Table 13-2 (Cont.): EDIT$ Options 


Value of 

Expression Effect 

32 Converts lowercase letters to uppercase. 

64 Converts left brackets ([) to left parentheses [(], and right 
brackets (]) to right parentheses [)]. 

128 Discards trailing spaces and tabs. (Same as TRM$ function.) 

256 Suppresses all editing for characters within quotation marks. If 


the string has only one quotation mark, VAX BASIC suppresses 
all editing for the characters following the quotation mark. 


All values are additive; for example, by specifying 168, you can: 


e Discard leading spaces and tabs (value 8) 
¢ Convert lowercase letters to uppercase (value 32) 
e Discard trailing spaces and tabs (value 128) 


The following program requests an input string, discards all spaces and 
tabs, converts lowercase letters to uppercase, and converts brackets to 
parentheses: 


Example 
LINPUT "PLEASE TYPE A STRING"; input_string$ 


new_string$ = EDIT$(input_string$, 2% + 32% + 64%) 
PRINT new_string$ 


END 

Output 

PLEASE TYPE A STRING? 88 abc ([TABJ[5,5] 
88ABC (5,5) 


13.7 Manipulating String Data with Multiple Maps 


Mapping a string storage area in more than one way lets you extract a 
substring from a string or concatenate strings. In the following example, 
the three MAP statements reference the same 108 bytes of data. 
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Example 


MAP (emprec) first_name$ = 10, & 
last_name$ = 20, & 
street_number$ = 6, & 
street$ = 15, & 
city$ = 20, & 
state$ = 2, & 
zip$ = 5, & 
wage_class$ = 2, & 
date_of_review$ = 8, & 
salary_ytd$ = 10, & 
tax_ytd$ = 10 

MAP (emprec) full_name$ = 30, & 
address$ = 48, & 


salary_info$ = 30 
MAP (emprec) employee_record$ = 108 


You can move data into a map in different ways. For instance, you can 
use terminal input, arrays, and files. In the following example, the READ 
and DATA statements are used to move data into a map. 


Example 

READ EMPLOYEE_RECORD$ 

DATA "WILLIAM DAVIDSON 2241 MADISON BLVD "& 
"SCRANTON PA14225A912/10/78$13, 325 .77$925 .31" 


Because all the MAP statements in the example shown above reference 
the same storage area (emprec), you can access parts of this area through 


the mapped variables as shown in Example 1 and Example 2. 


Example 1 


PRINT full_name$ 
PRINT wage_class$ 
PRINT salary_ytd$ 


Output 1 
WILLIAM DAVIDSON 


AQ 
$13,325.77 
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Example 2 


PRINT last_name$ 
PRINT tax_ytd$ 


Output 2 


DAVIDSON 
$925 .31 


You can assign a new value to any of the mapped variables. For instance, 
the following example prompts the user for changed information by 
displaying a menu of topics. The user can then choose which topics need 
to be changed and then separately assign new values to each variable. 


Example 


Loop_1: 
WHILE 1% = 1% 
INPUT "Changes? (please type YES or NO)"; CH$ 
EXIT Loop_1 IF CH$ = "NO" 
PRINT "1. FIRST NAME" 
PRINT "2. LAST NAME" 
PRINT "3. STREET NUMBER" 
PRINT "4. STREET" 
PRINT "5. CITY" 
PRINT "6. STATE" 
PRINT "7. ZIP" 
PRINT "8. WAGE CLASS" 
PRINT "9. DATE OF REVIEW" 
PRINT "10. SALARY YTD" 
PRINT "11. TAX YTD" 
INPUT "CHANGE NUMBER"; NUMBERY 
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SELECT NUMBER% 
CASE 1% 

INPUT “FIRST NAME"; first_name$ 
CASE 2% 

INPUT "LAST NAME"; last_name$ 
CASE 3% 

INPUT "STREET NUMBER"; street_number$ 
CASE 4% 

INPUT "STREET"; street$ 
CASE 5% 

INPUT "CITY"; city$ 
CASE 6% 

INPUT "STATE"; state$ 
CASE 7%, 

INPUT "ZIP CODE"; zip$ 
CASE 8% 

INPUT "WAGE CLASS"; wage_class$ 
CASE 9% 

INPUT "DATE OF REVIEW"; date_of_review$ 
CASE 10% 

INPUT "SALARY YTD"; salary_ytd$ 
CASE 11% 

INPUT "TAX YTD"; tax_ytd$ 
CASE ELSE 

PRINT "Invalid choice" 
END SELECT 

NEXT 
END 


Output 


Changes? (please type YES or NO)? YES 
1. FIRST NAME 

2 LAST NAME 

3. STREET NUMBER 
4 STREET 

5. CITY 

6. STATE 

7 ZIP 

8 WAGE CLASS 

9. DATE OF REVIEW 
10. SALARY YTD 
11. TAX YTD 


CHANGE NUMBER? 10 

SALARY YTD? 14,277.08 

Changes? (please type YES or NO)? YES 
CHANGE NUMBER? 11 

TAX YTD? 998.32 

Changes? (please type YES or NO)? NO 


See Chapter 9 and the VAX BASIC Reference Manual for more information 
on the MAP statement. 
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Chapter 14 
Program Segmentation 


Program segmentation is the process of dividing a program into small, 
manageable routines and modules. In a segmented or modular program, 
each routine or module usually performs only one logical function. You 
can therefore design and implement a modular program faster than a 
nonsegmented program. Program modularity also simplifies debugging 
and testing, as well as program maintenance and transportability. 


This chapter describes how to 


e Declare VAX BASIC subprograms 
e Write VAX BASIC subprograms 
e Share data among program units 


Subprograms processed by the VAX BASIC compiler conform to the VAX 
Procedure Calling Standard. This standard prescribes how arguments 
are passed, how values are returned, and how procedures receive and 
return control. Because VAX BASIC conforms to the VAX Procedure 
Calling Standard, a VAX BASIC subprogram or main program can call or 
be called by any procedure written in a language that also conforms to 
this standard. For information about calling non-BASIC procedures, see 
Chapter 21. 


Program Segmentation 14-1 


14.1 VAX BASIC Subprograms 


VAX BASIC has SUB, FUNCTION, and PICTURE subprograms. Each of 
these subprograms receives parameters and can modify parameters passed 
by reference or by descriptor. The differences between SUB, FUNCTION, 
and PICTURE subprograms are as follows: 


e FUNCTION subprograms must be declared with an EXTERNAL 
statement in the calling program. Declaring SUB and PICTURE 
subprograms is optional. 


e FUNCTION subprograms return a value; SUB and PICTURE subpro- 
grams do not. 


e PICTURE subprograms must be invoked with the DRAW statement 
and are reserved for use with VAX BASIC graphics. For more infor- 
mation on PICTURE subprograms, see Programming with VAX BASIC 
Graphics. 


All subprograms invoked by a VAX BASIC program must have unique 
names. A VAX BASIC program cannot have different subprograms with 
the same identifiers. 


Subprograms can return a value to the calling program by way of param- 
eters. You can use subprograms to separate routines that you commonly 
use. For example, you can use subprograms to perform file I/O opera- 
tions, to sort data, or for table lookups. 


You can also use subprograms to separate very large programs into 
smaller, more manageable routines, or you can separate modules that are 
modified often. If all references to system-specific features are isolated, it 
is easier to transport the program to a different system. VAX/VMS System 
Services and VAX Run-Time Library routines are specific to VAX/VMS 
systems; therefore, you should consider isolating references to them in 
subprograms. Chapter 21 describes how to access Run-Time Library 
routines and system services from VAX BASIC. 


You should also consider isolating complex processing algorithms that are 
used commonly. If complex processing routines are isolated, they can be 

shared by many programs while the complexity remains hidden from the 
main program logic. However, they can share data only if the data is 


e Passed as a parameter from the CALL statement or function invocation 
to the subprogram—see Section 14.2 


e Part of a MAP or COMMON block—see Chapter 8 for information 
about using MAP and COMMON statements 
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e Ina file—see Chapter 15 for more information about accessing data 
from a file 


All DATA statements are local to a subprogram. Each time you call a 
subprogram, VAX BASIC positions the data pointer at the beginning of the 
subprogram’s data. 


The data pointer in the main program is not affected by READ or 
RESTORE statements in the subprogram (in contrast with the RESTORE 
# statement, which resets record pointers to the first record in the file no 
matter where it is executed). Chapter 7 contains more information on the 
READ and RESTORE statements. For more information on the RESTORE 
# statement, see Chapter 15. 


14.1.1 SUB Subprograms 


A SUB subprogram is a program module that can be separately compiled 
and that cannot return a value. A SUB subprogram is delimited by the 
SUB and END SUB statements. You may use the EXTERNAL statement to 
explicitly declare the SUB subprogram. 


The END SUB statement does the following: 


e Marks the end of the SUB subprogram 
¢ Does not affect I/O operations or files 
e Releases the storage allocated to local variables 
e Returns control to the calling program 


The EXIT SUB statement transfers control to the statement lexically 
following the statement that invoked the subprogram. It is equivalent to 
an unconditional branch to an END SUB statement. 


The following SUB subprogram sorts two integers. If this SUB is invoked 
with actual parameter values that are already in sorted order, the EXIT 
SUB statement is executed and control returns to the calling program. 
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SUB sort_out (INTEGER X, INTEGER Y) 
DECLARE INTEGER temp 
IF X¥>Y 
THEN 
temp = X 
X=Y 
Y = temp 
ELSE 
EXIT SUB 
END IF 
END SUB 


14.1.2 FUNCTION Subprograms 


A FUNCTION subprogram is a program module that returns a value and 
can be separately compiled. It must be delimited by the FUNCTION and 
END FUNCTION statements. You use the EXTERNAL statement to name 
and explicitly declare the data type of an external function. 


The END FUNCTION statement does the following: 


e¢ Marks the end of a function subprogram 

e Does not affect I/O operations or files 

e Releases the storage allocated to local variables 

e Optionally specifies a return value for the function 
e Returns control to the calling program 


The EXIT FUNCTION statement immediately returns program control 

to the statement that invoked the function and optionally returns the 
function’s return value. It is equivalent to an unconditional transfer to the 
END FUNCTION statement. 


You can specify an expression with both the END FUNCTION and EXIT 
FUNCTION statements, which is another way of returning a function 
value. This expression must match the function data type, and it super- 
sedes any function assignment. For more information, see the VAX BASIC 
Reference Manual. 


The following function returns the volume of a sphere of radius R. If this 
function is invoked with an actual parameter value less than or equal to 
zero, the function returns zero. 
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Example 


FUNCTION REAL Sphere_volume (REAL R) 
IF R <= 0 
THEN 
Sphere_volume = 0.0 
ELSE 
Sphere_volume = 4/3 * PI * R *# 3 
END IF 
END FUNCTION 


The following example declares the FUNCTION subprogram and 
invokes it: 


Example 


PROGRAM call_sphere 
EXTERNAL REAL FUNCTION SPHERE_VOLUME(REAL) 
PRINT SPHERE_VOLUME(5 .925) 

END PROGRAM 


Note that this module is compiled separately from the FUNCTION 
subprogram. You can link these modules together to run the program 
from DCL level. To run the program in the BASIC environment, you 
follow these steps: 

1. Compile the function subprogram 

2. Load the resulting object module with the LOAD command 

3. Read in the main program with the OLD command 

4. Type RUN 

See Chapter 3 for more information about the LOAD command and 


linking and running multiple-unit programs. 


14.2 Declaring Subprograms and Parameters 


You declare a subprogram by naming it in an EXTERNAL statement in the 
calling program. You may also declare the data type of each parameter. 

If the subprogram is a function, the EXTERNAL statement also lets you 
specify the data type of the returned value. 
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The following statements are sample subprogram declarations using the 
EXTERNAL statement: 


EXTERNAL SUB my_sub (LONG, STRING) 
EXTERNAL GFLOAT FUNCTION my_func (GFLOAT, LONG, GFLOAT) 
EXTERNAL REAL FUNCTION determinant (LONG DIM(,)) 


Note that the parameter lists contain only data type and dimension 
information; they cannot contain any format or actual parameters. When 
the external procedure is invoked, VAX BASIC ensures that the actual 
parameter data type matches the data type specified in the EXTERNAL 
declaration. However, VAX BASIC does not check to make sure that 
the parameters declared in the EXTERNAL statement match those in the 
external routine. You must ensure that these parameters match. 


You can pass data of any VAX BASIC data type to a VAX BASIC subpro- 
gram, including RFAs and RECORDs. VAX BASIC allows you to pass up 
to 255 parameters, separated by commas. The data can be any one of the 
following: 

e Constants 

e Variables 

e Expressions 

e Functions 

e Array elements 

e Entire arrays (but not virtual arrays) 


For passing constants, variables, functions and array elements, you simply 
name them in the argument list. For example: 


CALL SUBO1(vari, var2) 
CALL SUBO2(Po_num%, Vouch, 66.67, Cust_list(5), FNA(B%)) 


However, when passing an entire array, you must use a special format. 
You specify the array name followed by commas enclosed in parentheses. 
The number of commas must be the number of array dimensions minus 
one. For example, array_name() is a one-dimensional array, array_name(,) 
is a two-dimensional array, array_name(,,) signifies a three-dimensional 
array, and so on. 


The following example creates a three-dimensional array, loads the array 
with values, and passes the array to a subprogram as a parameter. The 
subprogram can access and change values in array elements, and these 
changes remain in effect when control returns to the main program. 
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Example 


PROGRAM fill_array 
OPTION TYPE = EXPLICIT 
DECLARE LONG I,J,K, three_d(10,10,10) 
EXTERNAL SUB example_sub (LONG DIM(,,)) 
FOR I = 0 TO 10 
FOR J = 0 TO 10 
FOR K = 0 TO 10 
three_d(I,J,K) =I +J+K 
NEXT K 
NEXT J 
NEXT I 


CALL example_sub( three_d(,,)) 
END PROGRAM 


SUB example_sub( LONG X( , , )) 


END SUB 


If you do not specify data types for parameters, the default data type is 
determined by 


e The last specified parameter data type 
e An OPTION statement 


e A VAX BASIC compilation qualifier (for example, 
/REAL—_SIZE=DOUBLE) 


e The system default 


The last specified parameter data type overrides all the other default 
data types, the defaults specified in the OPTION statement override any 
compilation qualifiers and system defaults, and so on. See Chapter 3 for 
more information on the OPTION statement and establishing data type 
defaults. 


When you know the length of a string or the dimensions of an array at 
compile time, you can achieve optimum performance, by passing them 
BY REF. When you call programs written in other languages, the practice 
of declaring subprograms and specifying the data types of parameters 
becomes more important because other languages may not use the VAX 
BASIC default parameter-passing mechanisms. For more information on 
calling subprograms written in other languages, see Chapter 21. 
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14.3 Compiling Subprograms 


A VAX BASIC source file can contain multiple program units. When you 
compile such a file, VAX BASIC produces a single object file containing 
the code from all the program units. You can then link this object file to 
create an executable image. 


If the main program and subprograms are in separate source files, you can 
compile them separately from DCL level. For example, the following com- 
mand causes VAX BASIC to create MAIN.OBJ, SUB1.OBJ, and SUB2.OBJ 
by separating the file names with commas: 


$ BASIC main, subi,sub2 


To link these programs, you must specify all object files as input to the 
VAX/VMS Linker. 


Alternatively, you can compile multiple modules into a single object file at 
DCL command level by separating the file names with plus signs: 


$ BASIC maint+tsubi+sub2 


The plus signs used to separate the file names cause VAX BASIC to create 
a single object file named MAIN.OBJ from the three source modules. To 
link this program, you specify only one input file to the linker. Note that 
you cannot concatenate source files that do not contain line numbers. 


In the BASIC environment, you can compile multiple program units with 
a resulting single object file by using the APPEND command followed 
by the COMPILE command. For more information on the APPEND and 
COMPILE commands, see Chapter 3. 


When creating a multiple-unit program, follow these rules: 


e If the source file contains line numbers, then the line numbers for each 
subprogram must be numerically greater than the highest line number 
of all preceding subprograms. 


e Line numbers must be unique and no greater than 32767. 


e Each subprogram must end with an END SUB or END FUNCTION 
statement before the next subprogram begins. 


e If the source file contains line numbers, then text following an END 
SUB or END FUNCTION statement must begin on a numbered line. 
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e If the source file does not contain line numbers, then text following 
an END SUB or END FUNCTION statement must begin on a new 
physical line. 


Note that in a multiple-unit program that contains line numbers, any com- 
ments or statements following an END, END SUB, or END FUNCTION 
statement become part of the preceding subprogram unless they begin on 
a numbered line. In a multiple-unit program that does not contain line 
numbers, however, any comments following an END, END SUB, or END 
FUNCTION statement become part of the following subprogram if one 
exists. 


In the following example, the function Strip changes all brackets to 
parentheses in the string A$ or alpha, and strips all trailing spaces and 
tabs: 


Example 


PROGRAM scan 
EXTERNAL STRING FUNCTION Strip (STRING) 
A$ = "USER$DISK: [BASIC . TRYOUTS] Hd 
B$ = Strip( A$ ) 
PRINT B$ 

END PROGRAM 


FUNCTION STRING Strip( STRING alpha ) 
IF (POS( alpha, "[", 1%)) > 0% 
THEN Strip = EDIT$(alpha, 128% +64%) 
ELSE Strip = EDIT$(alpha, 128%) 
END IF 
END FUNCTION 


14.4 Invoking Subprograms 


The following sections describe how to 


e Invoke subprograms 
e Pass parameters to subprograms 
e Share data among program modules 
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14.4.1 


Invoking SUB Subprograms 


The CALL statement transfers control to a subprogram, and optionally 
passes arguments to it. The parameters in the CALL statement specify 
variables, constants, expressions, array elements, or entire arrays to 

be passed to the subprogram. You can also specify a function in the 
argument list; when you do this, VAX BASIC passes the value returned 
by the function to the subprogram. If possible, VAX BASIC converts the 
actual arguments to the data type specified in the EXTERNAL statement. 
VAX BASIC signals an error when the conversion is not possible. 


The following example shows a VAX BASIC main program calling a 
VAX BASIC subprogram. The main program prompts for three integers: 
A, B, and C. It then passes these variables as parameters to the SUB 
subprogram. The subprogram prints the sum of these variables and 
returns control to the calling program. 


Example 


PROGRAM get_input 
OPTION TYPE = EXPLICIT 
EXTERNAL SUB SUBO1(LONG, LONG, LONG) 
DECLARE LONG A, B, C 
INPUT "Please type three integers"; A, B, C 
CALL SUBO1 (A, B, C) 

END PROGRAM 


SUB SUBO1 (LONG X, LONG Y, LONG Z) 
PRINT "The sum is"; X + Y + Z 
END SUB 


14.4.2. Invoking FUNCTION Subprograms 


The following example performs the same task as the example shown in 
Section 14.4.1; however, this example uses a FUNCTION subprogram that 
returns the value to the main program and the main program prints the 
result. 
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Example 


PROGRAM invoke_funct 
EXTERNAL LONG FUNCTION FUNO1(LONG, LONG, LONG) 
DECLARE LONG A, B, C 
INPUT "Please type three integers"; A, B, C 
PRINT "The sum is"; FUNO1(A, B, C) 

END PROGRAM 


FUNCTION LONG FUNO1 (LONG X, LONG Y, LONG Z) 
FUNO1 = X+Y+Z 
END FUNCTION 


If you do not assign a value to the function name and you do not specify 
a return value on an EXIT FUNCTION or END FUNCTION statement, the 
function returns zero or the null string. 


Note that when writing FUNCTION subprograms, you must specify a data 
type for the function in both the main program EXTERNAL statement and 
the subprogram FUNCTION statement. This data type keyword specifies 
the data type of the value returned by the function subprogram. You 
should ensure that the data type specified in an EXTERNAL FUNCTION 
statement matches the data type specified in the FUNCTION statement. 


If you declare a FUNCTION subprogram with an EXTERNAL statement 
and use the CALL statement to invoke the function, it executes correctly 
but the function value is not available. Note that VAX BASIC still per- 
forms parameter validation when you invoke a function with the CALL 
statement. 


Note that you cannot use the CALL statement to invoke a string or packed 
decimal function. 


14.5 Returning Program Status 


A PROGRAM unit lets you return a status from a VAX BASIC image. To 
do this, you can optionally include an integer expression with the END 
PROGRAM and EXIT PROGRAM statements. After executing a program, 
you can examine this status by checking the DCL symbol $STATUS. By 
default, VAX BASIC returns a status of 1, indicating success. Success is 
signaled with an odd numbered status value, while an error is signaled 
with an even numbered value. $STATUS contains the same value as the 
integer expression for the exit status in the EXIT and END PROGRAM 
statements. Note that if a program is terminated with an EXIT PROGRAM 
statement, the expression on the EXIT PROGRAM statement overrides any 
expression on the END PROGRAM statement. 
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In the following example, exit_status contains the status value returned 
by the program. After program execution, $STATUS has the value of 
exit_status. You can examine the value of $STATUS and display the 
corresponding message text with the lexical function FSEMESSAGE at DCL 
level, as shown following this example: 


Example 
PROGRAM Venture 
DECLARE INTEGER exit_status, & 
REAL capital 
EXTERNAL LONG CONSTANT SS$_BADPARAM 
EXTERNAL SUB play_safe (INTEGER) , & 


minor_risk (INTEGER) ,major_risk (INTEGER) 
Exit_status = 1% 
SET NO PROMPT 


How_much: 
INPUT "Enter the amount of your free capital $";capital 
SELECT capital 
CASE = 0 
exit_status = SS$_BADPARAM 
EXIT PROGRAM exit_status 


CASE < 5000 
CALL play_safe(capital) 
CASE < 15000 
CALL minor_risk(capital) 
CASE < 50000 
CALL major_risk(capital) 
CASE ELSE 
PRINT "I can't cope with that amount, try again." 
END SELECT 


GOTO How_much 


END PROGRAM exit_status 


After program execution, you can examine the status of the program at 
DCL level: 


$ SHOW SYMBOL $STATUS 
$STATUS = "4X10" 
$ error_text = F$MESSAGE(%X10) 
$ SHOW SYMBOL error_text 
ERROR_TEXT = "“SYSTEM-W-BADPARAM, bad parameter value" 


The PROGRAM statement is always optional; EXIT PROGRAM and END 
PROGRAM are legal without a matching PROGRAM statement. Without 
a PROGRAM statement, these statements still exit the main compilation 
unit. The EXIT PROGRAM and END PROGRAM statements are not valid 
within SUB, FUNCTION, or PICTURE subprograms. 
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Chapter 15 


File Input and Output 


This chapter explains the VAX BASIC file organizations and record oper- 
ations that are implemented through VAX Record Management Services 
(VAX RMS). For a more thorough understanding of file organization 
and file and record operations, see the VAX Record Management Services 
Reference Manual. 


RMS stores data in physical blocks. A block is the smallest number of 
bytes VAX BASIC transfers in a read or write operation. On disk, a block 
is 512 bytes. On magnetic tape, it is between 18 and 8192 bytes. 


RMS stores one or more data records in each block. A data record can also 
be divided into smaller units, called fields. A data record can be smaller 
than, equal to, or larger than a disk block. 


15.1 Record Formats 


The format of a record determines how RMS stores the record in a block. 
You specify the record format in an OPEN statement. The following are 
valid VAX BASIC record formats: 

e Fixed-length records 

e  Variable-length records 

e Stream records 
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15.1.1 Fixed-Length Records 


Fixed-length records are all the same length. RMS stores fixed-length 
records as they appear in the record buffer, including any spaces or null 
characters following the data; this process is called padding. Processing 
these records involves less overhead than other record formats; however, 
this format can use disk storage space less efficiently than variable-length 
or stream records. 


15.1.2 Variable-Length Records 


Variable-length records can have different lengths, but no record can 
exceed a maximum size set for the file. When the record is written to 

a file, RMS adds a record length header that contains the length of the 
record (excluding the header) in bytes. When your program retrieves a 
record, this header is not included in the record buffer. While variable- 
length records usually make more efficient use of storage space than 
fixed-length records, manipulation of the record length headers generates 
processor overhead. 


15.1.3 Stream Records 


VAX BASIC interprets stream records as a continuous sequence, or stream, 
of bytes. Unlike the fixed- and variable-length formats, stream records do 
not contain control information such as record counts, segment flags, or 
other system-supplied boundaries. Stream records are delimited by special 
characters or character sequences called terminators. Note that stream 
record formats are valid only in sequential files. 


RMS defines three types of stream record format: 

e STREAM records can be delimited by any special character (usually a 
carriage return /line-feed pair). 

¢ STREAM_LF records must be delimited by a line-feed character. 

e STREAM_CR records must be delimited by a carriage return. 


While you can access existing files of any one of these stream record for- 
mats, VAX BASIC creates new stream files only in the STREAM format; 
you can create files of the other two stream record formats by modify- 
ing the RMS FAB control structure in a USEROPEN routine. For more 
information on USEROPEN routines, see Section 15.8.11. 
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15.2 File Organizations 


VAX BASIC provides several types of file organization: sequential, rela- 
tive, indexed, and virtual. If you do not specify a file organization when 
creating a file, the default is a terminal-format file (a sequential file with 
variable-length records). The following sections describe each type of file 
organization. 


15.2.1 Terminal-Format Files 


A terminal-format file is a sequential file of variable-length records. 
Terminal-format files are the default; that is, you create a terminal-format 
file when you do not specify a file organization when you open a file. You 
can then use the PRINT, INPUT, INPUT LINE, and LINPUT statements to 
access a terminal-format file. See Chapters 7 and 8 for more information 
about terminal-format files. 


15.2.2 Sequential Files 


A sequential file contains records that are stored in the order they are 
written. Sequential files can contain records of any valid VAX BASIC 
record format: fixed-length, variable-length, or stream. You usually read 
a sequential file from the beginning; therefore, a sequential file is most 
useful when you access the data sequentially each time you use it. You 
can also access sequential fixed-length records randomly by specifying a 
record number if the file resides on disk. In either case, sequential files 
can reside on both disk and magnetic tape devices, and those stored on 
disk support shared access. 
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15.2.3 Relative Files 


A relative file contains a series of “cells” that are numbered consecutively 
from 1 to n, where n represents the relative record number. Each cell can 
contain only a single record. For fixed-length records, the length of each 
cell equals the record length plus 1 byte. For variable-length records, the 
length of the cell equals the maximum record size plus 3 bytes. 


You can access records in a relative file either sequentially or randomly. 
The relative record number is the key value in random access mode; that 
is, to access a record in a relative file in random access mode, you must 
know the relative record number of that record. You can add records to a 
relative file either at the end of the file or into any empty cell. 


Relative files are most useful when randomly accessed and when the 
record can be identified by its cell number (for example, when inventory 
numbers correspond to cell numbers). Relative files support shared access. 
You can delete records from relative files, but not sequential files. 


15.2.4 Indexed Files 


An indexed file contains data records that are sorted in ascending or 
descending order according to a primary index key value. The index key 
is a record field (or set of fields) that determines the order in which the 
records are logically accessed. Keys must be variables declared in a MAP 
statement. Keys can be any one of the following: 


e © Strings 

¢ WORD integers 

e LONG integers 

e Quadword integers 

¢ Packed decimal numbers 


String keys can also be segmented; the key can be composed of up to 
eight string variables in a map. Quadword keys must be referenced using 
a record or group exactly 8 bytes long. 


Along with the primary index key value, you can also specify up to 254 
alternate keys; RMS creates one index for each key you specify. For each 
of these keys you can also specify either an ascending or descending 
collating sequence. Each index is stored as part of the file, and each 
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entry in the index contains a pointer to a record. Therefore, each key you 
specify corresponds to a sorted list of record pointers. 


An indexed file of library books, for example, might be ordered by book 
title; that is, the title of the book is the primary key for the file. The keys 
for alternate indexes might include the author’s name and the book’s 
Library of Congress number. Neither of these alternate indexes contains 
the actual records; instead, they contain sorted pointers to the appropriate 
records. 


Indexed files are most useful when randomly accessed or when you want 
to access the records in more than one way. 


15.2.5 Virtual Files 


A virtual file is a random access file that stores one or more data records or 
virtual array elements in each physical 512-byte disk block. You create a 
virtual file by specifying ORGANIZATION VIRTUAL as part of the OPEN 
statement. Apart from virtual arrays and compatibility with BASIC-PLUS 
and BASIC-PLUS-2, you should use sequential fixed-length instead of 
virtual files, as they provide the same capabilities. See Section 15.5 for 
more information on accessing the individual records in a disk block. 


15.3 Record Access and Record Context 


Record access modes determine the order in which your program retrieves 
or stores records in a file. They determine the record context: the current 
record and the next record to be processed. When your program success- 
fully executes any record operation, the current record and next record 
pointers can change. If a record operation is unsuccessful, these pointers 
do not change. 


The four record access modes valid for RMS are as follows: 


¢ Sequential access—valid on any file organization 


e Random-by-record number access—valid on sequential fixed and all 
relative files 


¢ Random-by-key access—valid on indexed files 


¢ Random-by-RFA (Record File Address) access—valid on any RMS file 
located on disk 
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With sequential access, the next record is the next logical record in the 
file. In the case of relative files, the next logical record is the next existing 
record (deleted or never-written records are skipped). In the case of 
indexed files, the next logical record is the record with the next ascending 
or descending value in the current key of reference depending on that 
key’s collating sequence. You can therefore access relative or indexed files 
sequentially by not specifying a relative record number or key value. 


You can also access sequential fixed-length and relative files randomly by 

record number; that is, you can specify the record number of the record to 
be retrieved. For relative files, this record number corresponds to the cell 

number of the desired record. 


You can access indexed files randomly by key. The key specification 
includes a primary or alternate key and its value. VAX BASIC retrieves 
the record corresponding to that value in the particular key chosen. 


You can access disk files of any organization by Record File Address 
(RFA); this means that you specify an RFA variable whose value uniquely 
identifies a particular record. The RFA requires six bytes of information. 
For more information about RFAs, see Section 15.6.10. 


15.4 1/0 and Record Buffers 


An I/O buffer is a storage area in your program that RMS uses to store 
data for I/O operations. You do not have direct access to 1/O buffers; 
they are controlled entirely by RMS. The I/O buffer holds blocks of data 
transferred from the device, and its size is always greater than or equal 
to that of the record buffer. For more information about the amount of 
storage allocated for I/O buffers, see the VAX Record Management Services 
Reference Manual. 


A record buffer is another storage area in your program. You have direct 
access to and control of the record buffer. When your program reads 

a record from a file, the information is transferred from the file to the 
I/O buffer in one large chunk of data, and then the requested record is 
transferred to the record buffer. When your program writes a record, data 
is transferred from the record buffer to the I/O buffer, and then to the file 
either when the I/O buffer is full or when other blocks need to be read in. 


You can use MAP statements to create static record buffers and associate 
program variables with areas (fields) of the buffer. Static record buffers are 
buffers whose size does not change during program execution and whose 
program variables are always associated with the same fields in the buffer. 
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You can create dynamic record buffers with either a MAP DYNAMIC or a 
REMAP statement. These statements, when used after a MAP statement, 

associate or reassociate a particular program variable with a different area 
(field) of the record buffer. However, the total size of a record buffer does 
not change during program execution. 


NOTE 


If you do not specify a map, you must use MOVE TO and 
MOVE FROM statements to transfer data back and forth from 
the record buffer to program variables. However, MOVE 
statements do not transfer data to or from a file. 


15.5 Accessing the Contents of a Record 


VAX BASIC provides several different methods for accessing the contents 
of a record: 

e MAP statement 

e MAP DYNAMIC, and REMAP statements (dynamic mapping) 

e MOVE statements 

e¢ FIELD statements 


The FIELD statement is a declining feature and is not recommended for 
new program development. DIGITAL recommends that you use either 
MAP statements, dynamic mapping or MOVE statements to access record 
contents. 


15.5.1 The MAP Statement 


Normally, a record is divided into predetermined fields, the sizes of which 
are known at compile time. The MAP statement creates the storage area 
for this record and determines its total size. 
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Example 1 


RECORD name_addr 
STRING last_name = 15, & 
street_name = 30, & 
INTEGER house_num 
END RECORD 
MAP (student_buffer) name_addr student_info 


Example 2 

MAP (Emp_rec) 
STRING Emp_name = 25, & 
LONG Badge, & 
STRING Address = 25, & 


STRING Department = 4 


15.5.2 The MAP DYNAMIC and REMAP Statements 


There are situations where predetermined fields are not applicable or 
possible. In these situations, you must perform record defielding in your 
program at run time. Using the MAP DYNAMIC statement, you can 
specify the variables in the map whose positions can change at run time. 
The REMAP statement then specifies the new positions of the variables 
named in the MAP DYNAMIC statement. 


The following example shows how you can use MAP, MAP DYNAMIC, 
and REMAP to deblock your record fields. The MAP statement allocates 
a storage area of 2048 bytes and names it Emp_rec. The MAP DYNAMIC 
statement specifies that the variables Emp_name, Badge, Address, and 
Department are all located in Emp_rec, and that their positions can be 
changed at run time with the REMAP statement. The REMAP statement 
then redefines these variables to their appropriate sizes. 


Example 
MAP (Emp_rec) FILL$ = 2048 


MAP DYNAMIC (Emp_rec) 
STRING Emp_nane, 
LONG Badge, 
STRING Address, 
STRING Department 


Seee 
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REMAP (Emp_rec) FILL$ = Record_offset, 
Emp_name = 25, 
Badge, 
Address = 25, 
Department = 4 


& & & & 


Note that when accessing virtual or sequential files, you can specify a 
RECORD clause for the GET statement. The following program opens a 
virtual file with each block containing 512 bytes. However, each block 
contains 4 logical records that are 128 bytes long. Each of these logical 
records consists of a 20-character first name field, a 44-character last name 
field, and a 64-character company name field. 


Example 


DECLARE WORD Record_number 
MAP (Virt) STRING FILL = 512 


MAP DYNAMIC (Virt) STRING First_name, & 
Last_nane, & 
Company 

OPEN "VIRT.DAT" FOR INPUT AS FILE #5, & 


VIRTUAL, MAP Virt 
Record_number = 1% 


WHEN ERROR IN 
WHILE -1% 
GET #5, RECORD Record_number 
FOR I% = 0% TO 3% 
REMAP (Virt) STRING FILL = (I% * 128%), & 
First_name = 20, & 
Last_name = 44, & 
Company = 64 
PRINT First_name, Last_name, Company 
NEXT I% 
Record_number = Record_number + 1% 
NEXT 


USE 
IF ERR = 11% 
THEN 
PRINT "Finished" 
CONTINUE 32767 
ELSE EXIT HANDLER 
END IF 
END WHEN 
END 


After the first 512-byte block is brought into memory, the FOR...NEXT 
loop deblocks the data into 128-byte logical records. At each iteration 
of the FOR...NEXT loop, the REMAP statement uses the loop variable to 
mask off 128-byte sections of the block. 
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For more information on the MAP DYNAMIC and REMAP statements, 
see Chapter 9 and the VAX BASIC Reference Manual. 


15.5.3 The MOVE Statement 


The MOVE statement defines data fields and moves them to and from the 
record buffer created by VAX BASIC. For example: 


MOVE FROM #9%, A$, Cost, Name$ = 30%, ID_num% 


This statement moves a record with four data fields from the record buffer 
to the variables in the list: 

e A string field A$ with a default length of 16 characters 

e A number field Cost of the default data type 

e¢ A second 30-character string field Name$ 

e An integer field ID_num% 


Valid variables in the MOVE list are as follows: 


e Scalar variables 
e Arrays 

e Array elements 
e = FILL items 


Because VAX BASIC dynamically assigns space for string variables, the 
default string length during a MOVE TO operation is the length of the 
string. The default for MOVE FROM is 16 characters. An entire array 
specified in a MOVE statement must include the array name, followed by 
n—1 commas, where n is the number of dimensions in the array. Note 
that these commas must be enclosed in parentheses. You specify a single 
array element by naming the array and the subscripts of that element. 
The following statement moves three arrays from the program to the 
record buffer. A$ specifies a one-dimensional string array, C specifies a 
two-dimensional array of the default data type, and D% specifies a three- 
dimensional integer array. B(3,2) specifies the element of array B that 
appears in row 3, column 2. 


MOVE TO #5%, A$(), C(,), D&C(,,), B(3,2) 
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Successive MOVE statements to or from the buffer start at the beginning 
of the record buffer. If a MOVE TO operation only partially fills the 
buffer, the rest of the buffer is unchanged. You use the GET statement 

to read a record from a file, and then you move the data from the buffer 
to variables and reference the variables in your program. A MOVE TO 
operation moves data from the variables into the buffer created by VAX 
BASIC. A PUT or UPDATE statement then moves the data from the buffer 
to the file. 


The following program opens file MOV.DAT, reads the first record into 
the buffer, and moves the data from the buffer into the variables specified 
in the MOVE FROM statement. 


Example 


DECLARE STRING Emp_name, Address, Department 
DECLARE LONG Badge 


OPEN "MOV.DAT" AS FILE #1%, & 
RELATIVE VARIABLE, & 
ACCESS MODIFY, ALLOW NONE, & 
RECORDSIZE 512% 

GET #1% 

MOVE FROM #1%, & 
Emp_name = 25, & 
Badge, & 
Address = 25, & 
Department = 4 

’ MOVE TO #1%, & 
Emp_name = 25, & 
Badge, & 
Address = 25, & 
Department = 4 

UPDATE #1% 

CLOSE #1% 

END 


The MOVE TO statement moves the data from the named variables 
into the buffer. The UPDATE statement writes the record back into file 
MOV.DAT. The CLOSE statement closes the file. 
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15.6 File and Record Operations 


You can perform a variety of operations on files and on the records within 
a file. The following is a list of all the file and record operations supported 
by VAX BASIC: 

e Open a file for processing with the OPEN statement 

e Locate a record in a file with the FIND statement 

e Read a record from a file with the GET statement 

e Write a record to a file with the PUT statement 

e Delete a record from a file with the DELETE statement 

e¢ Change the contents of a record field with the UPDATE statement 

¢ Unlock the last record accessed with the UNLOCK statement 

e Unlock all previously locked records with the FREE statement 

e Write data to a terminal-format file with the PRINT # statement 


e Reset the current record pointer to the beginning of a file with the 
RESTORE/RESET # statements 

e Delete all the records after a certain point; that is, truncate the records, 
with the SCRATCH statement 

e Rename a file with the NAME AS statement 

e Close an open file with the CLOSE statement 

e Delete an entire file with the KILL statement 


Note that before you can perform any operations on the records in a file, 
you must first open the file for processing. 


15.6.1 Opening Files 


The OPEN statement opens a file for processing, specifies the charac- 
teristics of the file to RMS, and verifies the result. Opening a file with 
the specification FOR INPUT specifies that you want to use an existing 
file. Opening a file with the specification FOR OUTPUT indicates that 
you want to create a new file. If you do not specify FOR INPUT or FOR 
OUTPUT, VAX BASIC tries to open an existing file. If no such file exists, 
VAX BASIC then creates a new file. 
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Clauses to the OPEN statement allow you to specify the characteristics 
of a file. All OPEN statement clauses concerning file or record format 
are optional when you open an existing file; those attributes that are not 
specified default to the attributes of the existing file. When you open 

an existing file, you must specify the file name, channel number, and 
unless the file is a terminal-format file, an organization clause. If you 
do not know the organization of the file you want to open, you can 
specify ORGANIZATION UNDEFINED. If you specify ORGANIZATION 
UNDEFINED, also specify RECORDTYPE ANY. 


If you do not specify a map in the OPEN statement, the size of your pro- 
gram’s record buffer is determined by the OPEN statement RECORDSIZE 
clause, or by the record size associated with the file. If you specify both 
a MAP clause and a RECORDSIZE clause in the OPEN statement, the 
specified record size overrides the size specified by the MAP clause. 


The following statement opens a new sequential file of stream format 
records: 


OPEN "TEST.DAT" FOR OUTPUT AS FILE #1%, & 
SEQUENTIAL STREAM 


The following example creates a relative file and associates it with a static 
record buffer. The MAP statement defines the record buffer’s total size 
and the data types of its variables. When the program is compiled, VAX 
BASIC allocates space in the record buffer for one integer, one 16-byte 
string, and one double-precision floating-point number. The record size is 
the total of these fields, or 28 bytes. All subsequent record operations use 
this static buffer for I/O to the file. 


Example 


MAP (Inv_item) LONG Part_number, & 
STRING Inv_name = 16, & 
DOUBLE Unit_price 

OPEN "INVENTORY.DAT" FOR OUTPUT AS FILE #1% & 
,»ORGANIZATION RELATIVE FIXED, ACCESS MODIFY & 
, ALLOW READ, MAP Inv_item 


The following OPEN statement opens a sequential file for reading only 
(ACCESS READ). Because the OPEN statement does not contain a MAP 
clause, VAX BASIC creates a record buffer. This record buffer is 100 bytes 
long. 


OPEN "CASE.DAT" AS FILE #1% & 
ORGANIZATION SEQUENTIAL VARIABLE & 
,»ACCESS READ & 
»RECORDSIZE 100% 
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When you do not specify a MAP statement, your program must use 
MOVE TO and MOVE FROM statements to move data between the record 
buffer and a list of variables. 


The OPEN statement for indexed files must have a MAP clause. 
Moreover, if you are creating an indexed file, a PRIMARY KEY clause 

is required. You can create a segmented index key containing more than 
one string variable by separating the variables with commas and enclosing 
them in parentheses. All the string variables must be part of the associ- 
ated map. In the following example, the primary key is made up of three 
string variables. This key causes the records to be sorted in alphabetical 
order according to the person’s last name, first name, and middle initial. 


MAP (Segkey) STRING First_name = 15, MI = 1, Last_name = 15 

OPEN "NAMES.IND" FOR OUTPUT AS FILE #1%, & 
ORGANIZATION INDEXED, & 
PRIMARY KEY (Last_name, First_name, MI), & 
MAP Segkey 


Note that there are restrictions on the maximum record size allowed for 
various file and record formats. See the VAX Record Management Services 
Reference Manual for more information. 


You can use logical names to assign a mnemonic name to all or part of 

a complete file specification, including node, device and directory. The 
advantage in using logical names is that programs do not depend on literal 
file specifications. You can define logical names: 


e From DCL command level with the ASSIGN or DEFINE command 
¢ From within a program with the SYS$CRELMN system service 


e From within the BASIC environment with the VAX BASIC command 
ASSIGN 


VAX BASIC supports any valid logical name as part of a file specification. 


A logical name specifies a 1- through 255-character name to be associated 
with the specified device or file specification. If the logical name specifies 
a device, you must end the logical name with a colon. The following 
example defines a logical name for a file specification: 


$ ASSIGN DUA1: [SENDER] PAYROL.DAT PAYROLL_DATA 
This example defines a logical name for a physical device: 
$ ASSIGN DUA2: DISK2: 


Once you define the logical name, you can reference that name in your 
program. 
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Example 


OPEN "PAYROLL_DATA" FOR INPUT AS FILE #1%, & 
ORGANIZATION SEQUENTIAL 

OPEN "DISK2:[SORT_DATA] SORT.LIS" FOR OUTPUT AS FILE #2%, & 
SEQUENTIAL VARIABLE 


These OPEN statements do not depend on the availability of DUA1: 
or DUA2: in order to work. If these devices are not available, you can 
simply redefine the logical names so that they specify other disk drives 
before running the program. In addition, you can redirect the entire 
file specification for PAYROLL_DATA to point to the test or production 
version of the data. 


For more information on logical names, see the Introduction to VAX/VMS. 


15.6.2 Creating Virtual Array Files 


VAX BASIC virtual arrays let you define arrays that reside on disk. You 
use them just as you would an ordinary array. You create a virtual array 
by dimensioning an array with the DIM # statement, then opening a 
VIRTUAL file on that channel. You access virtual arrays just as you do 
normal arrays. The following DIM # statement dimensions a virtual array 
on channel #1. The OPEN statement opens a virtual file that contains the 
array. The last program line assigns a value to one array element. 


Example 


DIM #1%, LONG Int_array(10,10,10) 
OPEN "VIRT.DAT" FOR OUTPUT AS FILE #1%, VIRTUAL 


Int_array(5,5,5) = 100% 


Note that you cannot redimension virtual arrays with an executable DIM 
statement. See Chapter 8 for more information on virtual arrays. 
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15.6.3 Locating Records 


The FIND statement locates a specified record and makes it the current 
record. Using the FIND statement to locate records can be faster than 
using a GET statement because the FIND statement does not transfer 
any data to the record buffer; therefore, it executes faster than a GET 
statement. However, if you are interested in the contents of a record, you 
must retrieve it with a GET operation. 


The FIND statement sets the current record pointer to the record just 
found, making it the target for a GET, UPDATE, or DELETE statement. 
(Note that you must have write access to a record before issuing a PUT, 
UPDATE, or DELETE operation.) A sequential FIND operation searches 
records in the following order: 


e¢ Sequential files from beginning to end 
e Relative files in ascending relative record or cell number order 


e Indexed files in ascending or descending order, based on the current 
key of reference and the key’s collating sequence 


For sequential fixed-length and relative files, you can find a particular 
record by specifying a RECORD clause. This is called a random access 
FIND. You can also perform a random access FIND for indexed files by 
specifying a key of reference, a relational test, and a key value. In the 
following example, the first FIND statement finds the first record whose 
key value either equals or follows SMITH in the key’s collating sequence. 
The second FIND statement finds the first record whose key value follows 
JONES in the key’s collating sequence. Each record found by the FIND 
statement becomes the current record. (Note that you can only have one 
current record at a time.) 


Example 


MAP (Emp) STRING Emp_name, LONG Emp_number, SSN 
OPEN "EMP.DAT" AS FILE #1%, INDEXED, 
ACCESS READ, 
MAP Emp, 
PRIMARY KEY Emp_name 
FIND #1%, KEY #0% NXEQ "SMITH" 
FIND #1%, KEY #0% NX "JONES" 


See 


The string expression can contain fewer characters than the key of the 
record you want to find. However, if you want to locate a record whose 
string key field exactly matches the string expression you provide, you 
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must pad the string expression with spaces to the exact length of the key 
of reference. For example: 


FIND #5%, KEY #0% EQ "TOM " 
FIND #5%, KEY #0% EQ "TOM" 


The first FIND statement locates a record whose primary key field equals 
"TOM ". The second FIND statement locates the first record whose 
primary key field begins with "TOM". 


Table 15-1 displays the status of the current record and next record 
pointers after both a sequential and a random access FIND. 


Table 15-1: Record Context After a FIND Operation 
Record Access File Current 
Mode Type Record Next Record 
Sequential FIND Sequential Record found Current record + 1 
Relative Record found Next existing record 
Indexed Record found Next record in current key order 
Random access FIND All Record found Unchanged 


Note that a random access FIND operation locates the specified record and 
makes it the current record, but the next record pointer does not change. 


You can specify an ALLOW clause to the FIND statement if you have 
opened the file with ACCESS MODIFY or ACCESS WRITE and have 
specified UNLOCK EXPLICIT. The ALLOW clause lets you control the 
type of lock that RMS puts on the records you access. ALLOW NONE 
specifies that no other users can access this record (this is the default). 
ALLOW READ lets other users read the record; however, they cannot 
perform UPDATE or DELETE operations to this record. ALLOW MODIFY 
specifies that other users can both read and write to this record. This 
means that other access streams can perform GET, DELETE, or UPDATE 
operations to the specified record. 


You can also specify a WAIT clause to the FIND statement; this clause 
allows you to wait for a record to become available in the event that it 
is currently locked by another process. In addition, you can specify a 
REGARDLESS clause; this clause allows you to read a locked record. 
For more information on the WAIT and REGARDLESS clauses, see 
Section 15.6.9. 
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15.6.4 Reading Records 


Table 15-2: 


Record Access 
Mode 


Sequential GET 
with FIND 


Sequential GET 
without FIND 


Random GET 


The GET statement moves a record from a file to a record buffer and 
makes the data available for processing. GET statements are valid on 
sequential, relative, and indexed files. You should not use GET statements 
on terminal-format files, or virtual array files. 


For sequential files, a sequential GET retrieves the next record in the 
file. For relative files, a sequential GET retrieves the next existing record. 
For indexed files, a sequential GET retrieves the record with the next 
ascending or descending value in the current key of reference, depending 
on that key’s collating sequence. 


Table 15-2 shows the current record and next record pointers after a 
GET operation. Note that the values of these pointers vary depending on 
whether or not the previous operation was a FIND. 


Record Context After a GET Operation 


File Current 

Type Record Next Record 

Sequential Record found Current record + 1 

Relative Record found Next existing record 

Indexed Record found Next record in current key 

Sequential Next record Next record + 1 

Relative Next existing Next existing record + 1 
record 

Indexed Next record in Record following next record in current 
current key key 

All Record specified | Next record in succession 


If you precede a sequential GET operation with a FIND operation, the 
current record is the one located by FIND. If you do not perform a FIND 
operation before a sequential GET operation, the current record is the next 
sequential record. 


The following example illustrates the use of the GET operation to sequen- 
tially access records in an indexed file. The example opens an indexed file 
and displays the first 25 records with serial numbers greater than AB2721 
in ascending primary key value order. 
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Example 


MAP (Bec) STRING Owner = 30%, LONG Vehicle_number, & 
STRING Serial_number = 22% 
OPEN "VEH.IDN" FOR INPUT AS FILE #2%, & 


ORGANIZATION INDEXED, PRIMARY KEY Serial_number, & 
MAP Bec, ACCESS READ 


GET #2%, KEY #0% EQ "AB2721" 
FOR I% = 1% TO 25% 
GET #2% 
PRINT "Vehicle Number = ";Vehicle_number 
PRINT "Owner is: ";Owner 
PRINT 
NEXT I% 


The following example performs random GET operations by specifying a 
record number: 


Example 
MAP (Bec) STRING Owner = 30%, LONG Vehicle_number, & 
STRING Serial_number = 22% 
OPEN "VEH.IDN" FOR INPUT AS FILE #2%, & 
ORGANIZATION SEQUENTIAL FIXED, & 


MAP Bec, ACCESS READ 
INPUT "Which record do you want"; AY 


WHILE (A% <> 0%) 
GET #2%, RECORD A% 
PRINT "The vehicle number is", Vehicle_number 
PRINT "The serial number is", Serial_number 
PRINT "The owner of vehicle";Vehicle_number; "is", Owner 
INPUT "Next Record"; A% 
NEXT 
CLOSE #2% 
END 


You can specify an ALLOW clause in a GET statement if you have 
opened the file with ACCESS MODIFY or ACCESS WRITE and UNLOCK 
EXPLICIT. The ALLOW clause lets you control the type of lock RMS 
places on the retrieved record. ALLOW NONE specifies that no other 
users can access this record (this is the default), ALLOW READ lets 
other access streams have read access to the record. That is, other users 
can retrieve the record, but cannot perform DELETE, PUT, or UPDATE 
operations on it. ALLOW MODIFY lets other access streams perform GET, 
DELETE, or UPDATE operations on the record. 
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If you are trying to access a locked record, VAX BASIC signals 
“Record/bucket locked” (ERR = 154). However, if you only need to 

read this record, you can override the lock with the REGARDLESS clause. 
The REGARDLESS clause allows you to read a locked record. Use caution 
when using the REGARDLESS clause because a record accessed in this 
way may be in the process of being changed by another program. 


Alternatively, you can also specify the WAIT clause on a GET statement; 
the WAIT clause allows you to handle record locked conditions by waiting 
for the record to become available. Note that if a WAIT clause is specified 
on a GET operation to a unit-record device such as a terminal, the integer 
expression indicates how long to wait for the I/O to complete, rather than 
how long to wait on a record locked condition. For more information, see 
Section 15.6.9. 


15.6.5 Writing Records 


For a file opened with ACCESS WRITE or ACCESS MODIFY, the PUT 
statement moves data from the record buffer to a file using the I/O buffer. 
PUT statements are valid on RMS sequential, relative, and indexed files. 


You cannot use PUT statements on terminal-format files, or virtual array 
files. 


Sequential access is valid on RMS sequential, relative, and indexed files. 
For sequential, variable and stream files, a sequential PUT operation adds 
a record at the end of the file. For sequential fixed and relative files, PUT 
writes records sequentially or randomly depending on the presence of a 
RECORD clause. For indexed files, RMS stores records in order of the 
primary key’s collating sequence. Therefore, you do not need to specify a 
random or sequential PUT. The following table shows the record context 
after both random and sequential PUT operations. 


Table 15-3: Record Context After a PUT Operation 


Record Access File Current 

Mode Type Record Next Record 
Sequential PUT Sequential None End of file 
Sequential PUT Relative None Next record 
Sequential PUT Indexed None Undefined 
Random PUT Relative None Unchanged 
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After a PUT operation, the current record pointer has no value. However, 
the value of the next record pointer changes depending on the file type 
and the record access mode used with the PUT operation. In a sequential, 
stream, or variable file, records can only be added at the end of the file; 
therefore, the next record after PUT is the end of the file. In a relative, 
sequential, or fixed file, the next record after a PUT operation is the next 
logical record. 


The following example opens a sequential file with ACCESS APPEND 
specified. For sequential files, this is almost identical to ACCESS WRITE. 
The only difference is that, with ACCESS APPEND, VAX BASIC positions 
the file pointer after the last record in the file when it opens the file for 
processing. All subsequent PUT operations append the new record to the 
end of the existing file. 


Example 


MAP (Buff) STRING Code = 4%, Exp_date = 9%, Type_desig = 32% 
OPEN "INV.DAT"FOR INPUT AS FILE #2%, & 
ORGANIZATION SEQUENTIAL FIXED, ACCESS APPEND, & 
MAP Buff 
WHILE -1% 
INPUT "What is the specification code" ;Code 
INPUT "What is the expiration date"; Exp_date 
INPUT "What is the designator" ;Type_desig 
PUT #2% 
NEXT 


If the current record pointer is not at the end of the file when you attempt 
a sequential PUT operation to a sequential file, VAX BASIC signals “Not at 
end of file” (ERR = 149). 


In the following example, the PUT statement writes records to an existing 
indexed file. In this case, the error message “Duplicate key detected” (ERR 
= 134) indicates that a record with a matching key field already exists, and 
you did not allow duplicates on that key. 
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Example 


10 MAP (Purchase_rec) STRING R_num = 5, & 
Dept_name = 10, & 
Pur_dat = 9 

20 OPEN "INFO.DAT"FOR OUTPUT AS FILE #2, & 


ORGANIZATION INDEXED FIXED, ACCESS WRITE, & 
PRIMARY KEY R_num, MAP Purchase_rec 

30 WHILE -1% 
INPUT "Requisition number" ;R_num 
INPUT "Department name" ;Dept_name 
INPUT "Date of purchase"; Pur_dat 
PRINT 
PUT #2%, 

NEXT 


Output 


Requisition number? 2522A 
Department name? COSMETICS 
Date of purchase? 15-JUNE-1985 


Requisition number? 2678D 
Department name? AUTOMOTIVE 
Date of purchase? 15-JUNE-1985 


Requisition number? 4167C 
Department name? AUTOMOTIVE 
Date of purchase? 6-JANUARY-1985 


Requisition number? 2522A 
Department name? SPORTING GOODS 
Date of purchase? 25-FEBRUARY-1985 


“4BAS-F-DUPKEYDET, Duplicate key detected 

~BAS-I-ON_CHAFIL, on channel 2 for file USER$$DISK: [MAGNUS] INFO.DAT;8 at 
user PC 0017E593 

-BAS-O-FROLINMOD, from line 30 in module DUPLICATES 

-RMS-F-DUP, duplicate key detected (DUP not set) 


15.6.6 Deleting Records 


The DELETE statement removes a record from a file that was opened with 
ACCESS MODIFY. After you have deleted a record you cannot retrieve it. 
DELETE works with relative and indexed files only. 


15-22 File Input and Output 


A successful FIND or GET operation must precede the DELETE operation. 
These operations make the target record available for deletion. In the 
following example, the FIND statement locates record 67 in a relative file 
and the DELETE statement removes this record from the file. Because the 
cell itself is not deleted, you can use the PUT statement to write a record 
into that cell after deleting its contents. 


FIND #1%, RECORD 67% 
DELETE #1% 


NOTE 


There is no current record after a deletion. The next record 
pointer is unchanged. 


15.6.7 Updating Records 


UPDATE writes a new record at the location indicated by the current 
record pointer. UPDATE is valid on RMS sequential, relative, and indexed 
files. 


The UPDATE statement operates on the current record, provided that you 
have write access to that record. In order to successfully update a variable- 
length record, you must know the exact size of the record you want to 
update. VAX BASIC has access to this information after a successful GET 
operation. If you have not performed a successful GET operation on the 
variable-length record, then you must specify a COUNT clause in the 
UPDATE statement that contains the record size information. 


An UPDATE will fail with the exception “No current record” (ERR = 131) 
if you have not previously established a current record with a successful 
GET or FIND. Therefore, when updating records you should include 
error trapping in your program to make sure all GET operations execute 
successfully. 


An UPDATE operation on a sequential file is valid only when: 


e The file containing the record is on disk 
e The new record is the same size as the one it is replacing 


¢ You have established a current record via a GET or FIND operation. 
Note that COUNT defaults to the size of the current record if a GET 
was performed. If a FIND operation was used to locate the current 
record, then you must supply a COUNT value. 
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The following program searches to find a record in which the L__name 
field matches the specified Search_name$. Once this record is found and 
retrieved, the Rm_num field of that record is updated; the program then 
prompts for another Search_name$. If a match is not found, VAX BASIC 
prints the message “No such record” and prompts the user for another 
Search_name$. The program ends when the user enters a null string for 
the Search_name$ value. 


Example 
20 MAP (AAA) STRING L_name = 60%, F_name = 20%, Rm_num = 8% 
30 OPEN "STU.DAT"FOR INPUT AS FILE #9%, & 
ORGANIZATION SEQUENTIAL FIXED, MAP AAA 
50 INPUT "Last name"; Search_name$ 
55 Search_name$ = EDIT$(Search_name$, -1%) 
60 IF Search_name$ = "" 
THEN GOTO 32010 
END IF 
65 RESTORE #9% 
70 WHEN ERROR IN 
75 GET #9% WHILE Search_name$ <> L_name 
USE 
IF ERR=11 
THEN 
PRINT "No such record" 
CONTINUE 50 
ELSE 
EXIT HANDLER 
END IF 
END WHEN 
80 INPUT "Room number" ;Rm_num 
90 UPDATE #9% 


100 GOTO 50 

32010 CLOSE #9% 

32030 PRINT "Update complete" 
32767 END 


NOTE 


An UPDATE operation invalidates the value of the current 
record pointer. The next record pointer is unchanged. 


When you update a record in a relative variable file, the new record can 
be larger or smaller than the record it replaces, provided that it is smaller 
than the maximum record size set for the file. When you update a record 
in an indexed variable file, the new record can also be larger or smaller 
than the record it replaces. The updated record: 


e Can be no longer than the maximum record size, if specified 
¢ Must include at least the primary key field 
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The following program updates a specified record on an indexed file: 


Example 


MAP (UPD) STRING Enrdat = 8%, LONG Part_num, Sh_num, REAL Cost 

OPEN "REC. ING"FOR INPUT AS FILE #8%, & 
INDEXED, MAP UPD, PRIMARY KEY Part_num 

INPUT "Part number to update"; A%, 


Loop1: 

WHILE -1% 
GET #8%, KEY #0%, EQ A% 
INPUT "Revised Cost is";Cost 
UPDATE #8% 
INPUT "Next Record"; A% 
IF A% = 0% 
THEN 

EXIT Loop1 

END IF 

NEXT 

CLOSE #87 

’ END 


If the new record either omits one of the old record’s alternate key fields 
or changes one of them, the OPEN statement must specify a CHANGES 
clause for that key field when the file is created. Otherwise, VAX BASIC 
signals the error “Key not changeable” (ERR = 130). 


15.6.8 Controlling Record Access 


When you open a file, VAX BASIC allows you to specify how you will 
access the file and what types of access you will allow other running 
programs while you have the file open. 


If you open a file for read access only (ACCESS READ), VAX BASIC 
by default allows other programs to have unrestricted access to the file. 
You can restrict access with an ALLOW clause only if the file’s security 
constraints allow you write access to the file. 


VAX BASIC by default prevents access by other programs to any file you 
open with ACCESS WRITE, ACCESS MODIFY, or ACCESS SCRATCH 
(sequential files only). This default action is equivalent to specifying the 
OPEN statement ALLOW NONE clause. To allow less restrictive access to 
the open file, specify ALLOW READ or ALLOW MODIFY. 
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When a file is open for read access only and you have not restricted access 
to other programs with ALLOW NONE, VAX BASIC allows other pro- 
grams to read any record in the file including records that your program 
is concurrently accessing. However, when you retrieve a record with the 
GET statement from a file you have opened with the intent to modify, 
VAX BASIC normally restricts other programs from accessing that record. 
This restriction is called locking. 


To allow other programs to access a record you have locked, you must 
release the lock on the record in one of the following ways: 


e Retrieve another record on the same channel. Unless you have 
opened the file with the UNLOCK EXPLICIT clause discussed below, 
this action will unlock the previous record. 


e Explicitly unlock the record with the UNLOCK or FREE statement. 
The UNLOCK statement releases the current record. The FREE 
statement releases all records locked on a given channel. 


e Perform an UPDATE operation on the record. An UPDATE statement 
causes the current record to be unlocked. 


e Close the file. 


In addition to the capability of restricting access via the OPEN statement 
ALLOW clause, VAX BASIC allows programs to explicitly control record 
locking on each record that is retrieved. To use explicit record locking on 
a file, the OPEN statement must include an UNLOCK EXPLICIT clause. 
You may then optionally specify an ALLOW clause on the GET and FIND 
statements. The ALLOW clause on a GET or FIND statement specifies 
the type of access allowed by other programs to the record while you 

are accessing it. For instance, the following statement specifies that other 
programs may read but not modify the records you have locked. 


GET #1, ALLOW READ 


If you specify UNLOCK EXPLICIT when opening a file, all records that 
you retrieve remain locked until you explicitly unlock them with a FREE, 
UNLOCK, or CLOSE statement. 
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15.6.9 Gaining Access to Locked Records 


If you are trying to access a record that is currently locked, one possible 
solution is to use the REGARDLESS clause on the GET or FIND statement. 
The REGARDLESS clause is useful when you are interested in having 
only read access to the specified record. Be aware, however, that using 
the REGARDLESS clause to read a locked record can lead to unexpected 
results because the record you read can be in the process of being changed 
by another program. 


Another solution is to include a WAIT clause on the GET or FIND state- 
ment. Note that you cannot specify a WAIT clause and a REGARDLESS 
clause on the same statement line. By specifying the WAIT clause, you 
can tell RMS to wait for a locked record to become available. You can 
optionally specify an integer expression from 0 through 255 with the 
WAIT clause. This integer expression indicates the number of seconds 
RMS should wait for a locked record to become available. If the record 
does not become available within the specified number of seconds, RMS 
signals the error “Keyboard wait exhausted” (ERR=15). 


If you do not specify an integer expression with the WAIT clause, RMS 
waits indefinitely for the record to become available. Once the record 
becomes available, RMS delivers the record to the program. 


Note that a deadlock condition can occur when you cause RMS to wait 
indefinitely for a locked record. A deadlock condition occurs when 

two users simultaneously try to access locked records in each other’s 
possession. When a deadlock occurs, RMS signals the error, “RMS$_ 
DEADLOCK”. In turn, VAX BASIC signals the error, “Detected deadlock 
error while waiting for GET or FIND” (ERR=193). To handle this error, 
you can either stop trying to access the particular record, or, if you must 
access the record, free all locked records (regardless of the channel) and 
then attempt the GET or FIND again. You need to unlock all records 
because you cannot know which record the other process wants. 


NOTE 


If the timeout value specified in the WAIT clause is less than 
the SYSGEN parameter DEADLOCK_WAIT, then a "keyboard 
wait exhausted” (ERR=15) message can indicate that either the 
record did not become available during the specified time, or 
there is an actual deadlock situation. However, if the timeout 
value is greater than the SYSGEN parameter DEADLOCK_— 
WAIT, the system correctly specifies that a deadlock situation 
has occurred. 
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The following example uses the WAIT clause to overcome a record locked 
condition and traps the resulting error condition: 


Example 


MAP (worker) STRING first_name = 10, & 
last_name = 20, & 
badge_number = 6, & 

LONG dept_number 


MAP (departments) STRING dept_name = 10, & 
LONG dept_code 


OPEN "Employee_data.dat" FOR INPUT AS FILE #14, & 
INDEXED FIXED, MAP worker, ACCESS MODIFY, & 
PRIMARY badge_number 


OPEN "departments.dat" FOR INPUT AS FILE #2, & 
INDEXED FIXED, MAP departments, ACCESS MODIFY, & 
PRIMARY dept_code 


WHEN ERROR IN 
WHILE -1% 
GET #1, WAIT 
WHEN ERROR USE time_expired_handler 
GET #2%, KEY #0 EQ dept_number, & 
WAIT 10% 
END WHEN 
PRINT badge_number, dept_name 
NEXT 
USE 
SELECT ERR 
CASE = 11% 
PRINT "End of file reached" 
CLOSE 1%, 2% 
CASE = 193% 
PRINT "Deadlock detected" 
UNLOCK #2% 
RETRY 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END WHEN 
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HANDLER time_expired_handler 
IF ERR = 15% OR ERR = 193% 
THEN 
PRINT "Department info not available for:" 
PRINT "Employee "; badge_number 
PRINT "Going on to next record." 
CONTINUE 
ELSE 
EXIT HANDLER 
END IF 
END HANDLER 
END PROGRAM 


The first WHEN ERROR block traps any deadlock conditions. The WHEN 
ERROR handler unlocks the current record on channel #2 in case another 
program is trying to access it and then retries the operation. The detached 
handler for the second WHEN ERROR block traps timeout errors and 
deadlock errors. If the desired information does not become available 

in the specified amount of time, or a deadlock condition occurs, the 
employee’s badge number is printed out with an appropriate message, and 
the GET statement tries to retrieve the next record in the sequence. 


15.6.10 Accessing Records by Record File Address 


A Record File Address (RFA) uniquely specifies a record in a file. 
Accessing records by RFA is therefore more efficient and faster than 
other forms of random record access. 


Because an RFA requires six bytes of storage, VAX BASIC has a special 
data type, RFA that denotes variables that contain RFA information. 
Variables of data type RFA can be used only with the I/O statements and 
functions that use RFA information, and in comparison and assignment 
statements. You cannot print these variables or use them in any arithmetic 
operation. However, you can compare RFA variables using the equal to 
(=) and not equal to <> relational operators. 


You cannot create named constants of the RFA data type. However, you 
can assign values from one RFA variable to another, and you can use RFA 
variables as parameters. 


Accessing a record by RFA requires three steps: 


1. Explicitly declare the variable or array of data type RFA to hold the 
address. 
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2. Assign the address to the variable or array element. You can do 
this either with the GETRFA function, or by reading a file of RFAs 
generated by previous GETRFA functions or by the VAX/VMS Sort 
Utility. 

3. Specify the variable in the RFA clause of a GET or FIND statement. 


The GETRFA function returns the RFA of the last record accessed on 

a channel. Therefore, you must access a record in the file with a GET, 
FIND, or PUT statement before using the GETRFA function. Otherwise, 
GETRFA returns a zero, which is an invalid RFA. The following example 
declares an array of type RFA containing 100 elements. After each PUT 
operation, the RFA of the record is assigned to an element of the array. 
Once the RFA information is assigned to a program variable or array 
element, you can use the RFA clause on a GET or FIND statement to 
retrieve the record. 


Example 


DECLARE RFA R_array(1 TO 100) 

DECLARE LONG I 

MAP (XYZ) STRING A = 80 

OPEN "TEST.DAT" FOR OUTPUT AS FILE #1, & 
SEQUENTIAL, MAP XYZ 

FOR I = 1% TO 100% 


PUT #1 
R_array(I) = GETRFA(1%) 
NEXT I 


You can use the RFA clause on GET statements for any file organization; 
the only restriction is that the file must reside on a disk that is accessible to 
the node that is executing the program. The following example continues 
the previous one. It randomly retrieves the records in a sequential file by 
using RFAs stored in the array. 
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Example 


DECLARE RFA R_array(1% TO 100%) 

DECLARE LONG I 

MAP (XYZ) STRING A = 80 

OPEN "TEST.DAT" FOR OUTPUT AS FILE #1, & 
SEQUENTIAL, MAP XYZ 

FOR I = 1% TO 100% 


PUT #1 
R_array(I) = GETRFA(1%) 
NEXT I 


WHILE -1% 
PRINT “Which record would you like to see"; 
INPUT "(type a carriage return to exit)";Rec_num% 
EXIT PROGRAM IF Rec_num%, = 0% 
GET #1, RFA R_array(Rec_num%) 
PRINT A 
NEXT 


15.6.11 Transferring Data to Terminal-Format Files 


The PRINT # statement transfers program data to a terminal-format file. 
In the following example, the INPUT statements prompt the user for three 
values: S_name$, Area$, and Quantity%. Once these values are entered, 
the PRINT # statement writes these values to a terminal-format file that is 
open on channel #4. | 


Example 


FOR I% = 1% TO 10% 
INPUT "Name of salesperson": S_name$ 
INPUT "Sales district"; Area$ 
INPUT "Quantity sold"; Quantity 
PRINT #4%, S_name$, Area$, Quantity/ 
NEXT I% 


If you do not specify an output list in the PRINT # statement, a blank 
line is written to the terminal-format file. A PRINT statement without a 
channel number transfers program data to a terminal. See Chapter 7 for 
more. information. 
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15.6.12 Resetting the File Position 


The RESTORE # statement resets the current record pointer to the begin- 
ning of the file; it does not change the file. RESET # is a synonym for 
RESTORE. For example: 


RESTORE #3%, KEY #2% 
RESET #3% 


The RESTORE # statement restores the file in terms of the second alter- 
nate key. The RESET # statement restores the file in terms of the primary 
key. 


The RESTORE # statement can be used by all RMS file organizations. 
RESTORE without a channel number resets the data pointer for READ 
and DATA statements but does not affect any files. 


15.6.13 Truncating Files 


The SCRATCH statement is valid only on sequential files. Although you 
cannot delete individual records from a sequential file, you can delete all 
records starting with the current record through to the end of the file. In 
order to do this, you must first specify ACCESS SCRATCH when you 
open the file. 


To truncate the file, locate the first record to be deleted. Once the current 
record pointer points to this record, execute the SCRATCH statement. The 
following program locates the thirty-third record and truncates the file 
beginning with that record. 


Example 


OPEN "MMM.DAT" AS FILE #2%, & 
SEQUENTIAL FIXED, ACCESS SCRATCH 


first_bad_record = 33% 


FIND #2%, RECORD first_bad_record 
SCRATCH #2% 

CLOSE #2% 

END 


SCRATCH does not change the physical size of the file; it reduces the 
amount of information contained in the file. (You can use the DCL 
command SET FILE/TRUNCATE to truncate the excess file space.) 
Therefore, you can write records with the PUT statement immediately 
after a SCRATCH operation. 
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15.6.14 Renaming Files 


If the security constraints permit, you can change the name or directory of 
a file with the NAME...AS statement. For example: 


NAME "MONEY.DAT" AS "ACCOUNTS .DAT" 


This statement changes the name of the file MONEY.DAT to 
ACCOUNTS.DAT. 


NOTE 


The NAME...AS statement can change only the name and 
directory of a file; it cannot be used to change the device name. 


You must always include an output file type because there is no default. 
If you use the NAME...AS statement on an open file, the new name does 
not take effect until you close the file.. 


15.6.15 Closing Files and Ending 1/0 


All programs should close files before the program terminates. However, 
VAX BASIC automatically closes files in the following situations: 


e Atan END, END PROGRAM, or EXIT PROGRAM statement 


e When it completes the last statement in the program if no END 
statement exists 


e While executing a CHAIN statement 


VAX BASIC does not close files after executing a STOP, END SUB, END 
FUNCTION, or END PICTURE statement. 


The CLOSE statement closes files and disassociates these files and their 
buffers from the channel numbers. If the file is a magnetic tape device 
and the data is written to a tape, CLOSE writes trailer labels at the end of 
the file. The following is an example of the CLOSE statement: 


Example 
CLOSE #1% 
BY = 4%, 


CLOSE #2%, BX, 7% 
CLOSE I% FOR 1% = 1% TO 20% 
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15.6.16 Deleting Files 


If the security constraints permit, you can delete a file with the KILL 
statement. 


KILL "TEST.DAT" 


This statement deletes the file named TEST.DAT. Note that this statement 
deletes only the most current version of the file. Do not omit the file type, 
because there is no default. You can delete only one file at a time; to 
delete all versions of a file matching a file specification, use the Run-Time 
Library routine LIBS] DELETE_FILE. 


You can delete a file that is currently being accessed by other users; 
however, the file is not deleted until all users have closed it. You cannot 
open or access a file once you have deleted it. 


15.7 File-Related Functions 


VAX BASIC provides built-in functions for finding 

e The characteristics of the last file opened (FSP$) 

e The number of bytes moved in the last I/O operation (RECOUNT) 
e The file status (STATUS, VMSSTATUS, and RMSSTATUS) 


These functions are discussed in the following sections. 


15.7.1 The FSPS Function 


If you do not know the organization of a file, you can find out by open- 
ing the file for input with the ORGANIZATION UNDEFINED and 
RECORDTYPE ANY clauses. Your program can then use the FSP$ 
function to determine the characteristics of that file. Your program must 
execute FSP$ immediately after the OPEN FOR INPUT statement. 
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Example 


RECORD FSP_data 
VARIANT 
CASE 
BYTE Rat 
BYTE Org 
WORD Max_record_size 
LONG File_size 
WORD Bucketsize_blocksize 
WORD Num_keys 
LONG Max_record_number 
CASE 
Ret_string = 16 
END RECORD 


DECLARE FSP_data File_chars 


OPEN "FIL.DAT" FOR INPUT AS FILE #1%, & 
ORGANIZATION UNDEFINED, & 
RECORDTYPE ANY, ACCESS READ 

File_chars: :Ret_string = FSP$(1%) 


e Rat returns the low byte that is the RMS record attributes (RAT) field. 
¢ Org returns the high byte that is the RMS organization (ORG) field. 

e Max_record_size returns the RMS maximum record size (MRS) field. 
e File_size returns the RMS allocation quantity (ALQ) field. 


e Bucketsize_blocksize returns the RMS bucket size (BKS) field for disk 
files or the RMS block size (BLS) field for magnetic tape files. 


¢ Num_keys returns the number of keys. 
e Max_—record_number returns the RMS maximum record number (MRN) 
field if the file is a relative file. 


Note that FSP$ returns zeros in bytes 9 through 12. For more information, 
see the VAX Record Management Services Reference Manual. 
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15.7.2 The RECOUNT Function 


Read operations can transfer varying amounts of data. The system variable 
RECOUNT contains the number of characters (bytes) read after each read 
operation. 


After a read operation from your terminal, RECOUNT contains the 
number of characters transferred, including the line terminator. After 
accessing a record, RECOUNT contains the number of characters in the 
record. 


RECOUNT is reset by every read operation on any channel, including 
the controlling terminal. Therefore, if you need to use the value of 
RECOUNT, copy it to another variable before executing another read 
operation. RECOUNT is undefined if an error occurs during a read 
operation. 


RECOUNT is often used as the argument to the COUNT clause in the 
UPDATE or PUT statement for variable-length files. The following se- 
quence of statements ensures that the output record on channel #5 is the 
same length as the input record on channel #4. 


Example 


GET #4% 
bytes_read/, = RECOUNT 


PUT #5%, COUNT bytes_ready, 


15.7.3 The STATUS, VMSSTATUS, and RMSSTATUS Functions 


The STATUS function accesses the status longword that contains char- 
acteristics of the last opened file. If an error occurs during an input 
operation, the value of STATUS is undefined. If an error does not occur, 
the six low-order bits of the returned value contain information about the 
type of device accessed by the last input operation. These bits correspond 
to the following devices: 

e If bit 0 is set, the device type is a record-oriented device. 

e If bit 1 is set, the device type is a carriage control device. 

e If bit 2 is set, the device type is a terminal. 


e If bit 3 is set, the device type is a directory oriented device. 
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e If bit 4 is set, the device type is a single directory device. 


e If bit 5 is set, the device type is a sequential block-oriented device 
(magnetic tape or TK50). 


Both the VMSSTATUS and RMSSTATUS functions are used to deter- 
mine which non-BASIC error caused a resulting VAX BASIC error. In 
particular, VMSSTATUS can be used for any non-BASIC errors, while 
RMSSTATUS is used specifically for RMS errors. For more information on 
these functions, see Chapter 17 and the VAX BASIC Reference Manual. 


15.8 OPEN Statement Options 


This section explains the OPEN statement keywords that enable you to 
control how a file is created or opened. These keywords are as follows: 


BUCKETSIZE 
BUFFER 
CONNECT 
CONTIGUOUS 
DEFAULTNAME 
EXTENDSIZE 
FILESIZE 
NOSPAN 
RECORDTYPE 
TEMPORARY 
USEROPEN 
WINDOWSIZE 


15.8.1 The BUCKETSIZE Clause 


The BUCKETSIZE clause applies only to relative and indexed files. A 
bucket is a logical storage structure that RMS uses to build and maintain 
relative and indexed files on disk devices. A bucket consists of 1 or more 
disk blocks. The default bucket size is the recordsize rounded up to a 
block boundary. Although RMS defines the bucket size in terms of disk 
blocks, the BUCKETSIZE clause specifies the number of records a bucket 
contains. For example: 


OPEN "“"STOCK_DATA.DAT" FOR OUTPUT AS FILE #1%, & 
ORGANIZATION RELATIVE FIXED, BUCKETSIZE 12% 
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This example specifies a bucket containing approximately 12 records. RMS 
reads in entire buckets into the I/O buffer at once, and a GET statement 
transfers one record from the I/O buffer to your program’s record buffer. 


When you open an existing relative or indexed file and specify a bucket 
size other than that originally assigned to the file, VAX BASIC signals “File 
attributes not matched” (ERR = 160). — 


Records cannot span bucket boundaries. Therefore, when you specify a 
bucket size in your program, you must consider the size of the largest 
record in the file. Note that a bucket must contain at least one record. 
Buckets in both relative and indexed files contain information in ad- 
dition to the records stored in the bucket. You should take this into 
consideration. 


There are two ways to establish the number of blocks in a bucket. The 
first is to use the VAX BASIC default. The second is to specify the ap- 
proximate number of records you want in each bucket. VAX BASIC then 
calculates a bucket size based on that number. 


The default bucket size assigned to relative and indexed files is as small as 
possible. A small bucket size, however, is rarely desirable. 


VAX BASIC selects a default bucket size depending on 


e The record length 
e The file organization (relative or indexed) 
e The record format 


If you do not define the BUCKETSIZE clause in the OPEN statement, VAX 
BASIC does the following: 


e Assumes that there is a minimum of one record in the bucket 
e Calculates a size | 
e Assigns the appropriate number of blocks 


Note that when you specify a bucket size for files in your program, you 
must keep in mind the space versus speed trade-offs. A large bucket 
size increases file processing speed because a greater amount of data is 
available in memory at one time. However, it also increases the memory 
space needed for buffer allocation and the processing time required to 
search the bucket. Conversely, a small bucket size minimizes buffer 
requirements, but increases the number of accesses to the storage device, 
thereby decreasing the speed of operations. 
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DIGITAL recommends that you use the DCL command EDIT/FDL to 
design files used in production applications where performance is a 
concern. 


15.8.2 The BUFFER Clause 


The BUFFER keyword applies to disk files of any organization. In the case 
of sequential files, the BUFFER clause sets the number of blocks read in 
on each disk access. For relative and indexed files, the BUFFER clause 
determines the number of I/O buffers that are allocated. In general, the 
VAX/VMS operating system supplies adequate defaults for all file types; 
therefore the BUFFER clause is rarely necessary. 


You can specify up to 127 buffers as either a positive or a negative 
number: 


e If(0 < BUFFER < 127), RMS allocates enough space for the speci- 
fied number of buckets. 


e If (-128 < BUFFER < 0), VAX BASIC allocates the absolute value of 
the specified number of buffers. 


e If (BUFFER = 0), VAX BASIC allocates the process default for the 
particular file organization and device—this value is usually adequate. 


15.8.3 The CONNECT Clause 


The CONNECT clause can be used only on indexed files. CONNECT lets 
you process different groups of records on different indexed keys or on 
the same key without incurring all of the RMS overhead of opening the 
same file more than once. For example, a program can read records in 
an indexed file sequentially by one key and randomly by another. Each 
stream is an independent, active series of record operations. 


Example 


MAP (Indmap) WORD Emp_nun, 
STRING Emp_last_name = 20, 
SINGLE Salary, 
STRING Wage_code = 2 
OPEN "IND.DAT" FOR INPUT AS FILE #1%, 
ORGANIZATION INDEXED, 
MAP Indmap, 
PRIMARY KEY Emp_nunm, 
ALTERNATE KEY Emp_last_name 


& & & 


RB ee eS 
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OPEN "IND.DAT" FOR INPUT AS FILE #2% 
ORGANIZATION INDEXED, 
MAP Indmap, 
CONNECT 1 


R & & 


OPEN "IND.DAT" FOR INPUT AS FILE #3% 
ORGANIZATION INDEXED, 
MAP Indmap, 
PRIMARY KEY Emp_nun, 
ALTERNATE KEY Wage_code, 
CONNECT 1 


& & & & & 


The channel on which you open the file for the first time is called the 
parent. The CONNECT clause specifies another channel on which you 
access the same file; connected channels are called children. More than 
one OPEN statement can connect to the parent channel; however, you 
cannot connect to a channel that has already been connected to another 
channel. 


15.8.4 The CONTIGUOUS Clause 


A contiguous file with physically adjoining blocks minimizes disk search- 
ing and decreases file access time. Once the system knows where a 
contiguous file starts on the disk, it does not need to use as many retrieval 
pointers to locate the pieces of that file. Rather, it can access data by cal- 
culating the distance from the beginning of the file to the desired data. If 
there is not enough contiguous disk space, VAX BASIC allocates as much 
contiguous space as possible. (For truly contiguous records, you must use 
the USEROPEN clause and set the CTG bit in the FAB FOP field—see the 
VAX Record Management Services Reference Manual. 


Opening a file with both the FILESIZE and CONTIGUOUS clauses 
preextends the file contiguously or in as few disk extents as possible. 
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15.8.5 The DEFAULTNAME Clause 


The DEFAULTNAME clause in the OPEN statement lets you specify a 
default file specification for the file to be opened. It is valid with all file 
organizations. VAX BASIC uses the DEFAULTNAME clause for any part 
of the file specification that is not explicitly supplied. 


Example 


LINPUT "Next data file"; Fil$ 

OPEN Fil$ FOR INPUT AS FILE #5%, & 
ORGANIZATION SEQUENTIAL, & 
DEFAULTNAME “USER$DEVICE: .DAT" 


The DEFAULTNAME clause supplies default values for the device, di- 
rectory, and file type portions of the file specification. Typing ABC in 
response to the “Next data file?” prompt causes VAX BASIC to try to open 
USER$DEVICE:ABC.DAT. 


VAX BASIC uses the DEFAULTNAME values only if you do not supply 
those parts of the file specification appearing in the DEFAULTNAME 
clause. For example, if you type SYS$DEVICE:ABC in response to the 
prompt, VAX BASIC tries to open SYS$DEVICE:ABC.DAT. In this case, 
SYS$DEVICE: overrides the device default in the DEFAULTNAME clause. 
Any part of the file specification still missing is filled in from the current 
default device and directory of the process. 


15.8.6 The EXTENDSIZE Clause 


The EXTENDSIZE attribute determines how many disk blocks RMS adds 
to the file when the current allocation is exhausted. The EXTENDSIZE 
clause only has an effect when creating a file. You specify EXTENDSIZE 
as a number of blocks. For example: 


OPEN "TSK.ORN" FOR OUTPUT AS FILE #2%, & 
ORGANIZATION RELATIVE, EXTENDSIZE 128% 


The EXTENDSIZE clause causes RMS to add 128 disk blocks whenever 
the current space allocation is exhausted and the file must be extended. 


The value you specify must conform to the following requirements: 


¢ It must be specified when you create the file 
e It cannot exceed 65,535 disk blocks 
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If you specify zero, the extension size equals the RMS default value. The 
EXTENDSIZE value can be overridden for single OPEN operations. 


15.8.7 The FILESIZE Clause 


With the FILESIZE attribute, you can allocate disk space for a file when 
you create it. The following statement allocates 50 blocks of disk space for 
the file “VALUES.DAT"”: 


OPEN "VALUES.DAT" FOR OUTPUT AS FILE #3%, FILESIZE 50% 
Preextending a file has several advantages: 


e The system can create a complete directory structure for the file, 
instead of allocating and mapping additional disk blocks when needed. 


e You reserve the needed disk space for your application. This ensures 
that you do not run out of space when the program is running. 


e Preextension can make some of the file’s disk blocks contiguous, 
especially when used with the CONTIGUOUS keyword. 


Note that preextension can be a disadvantage if it allocates disk space 
needed by other users. The FILESIZE clause is ignored when VAX BASIC 
opens an existing file. 


15.8.8 The NOSPAN Clause 


By default, sequential files allow records to cross or span block boundaries. 
If records cross block boundaries, RMS packs records into the file end- 
to-end throughout the file, leaving space for control information and 
padding. 


The NOSPAN clause overrides this default, forcing records to fit into indi- 
vidual blocks (with space provided for control information and padding). 
When block boundaries restrict records, fixed-length records must be less 
than 512 bytes, and variable-length records less than 510 bytes. This 
can waste extra bytes at the end of each block. However, when records 
span block boundaries, RMS writes records end-to-end without regard 
for block boundaries. For example, if you specify NOSPAN, only four 
120-byte records fit into a disk block. If you do not specify NOSPAN, 
VAX BASIC begins writing the fifth record in the block, and continues 
writing that record in the next block. This minimizes wasted disk space 
and improves the file’s capacity, at the minimal expense of increased 
processing overhead. 
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15.8.9 The RECORDTYPE Clause 


The RECORDTYPE clause lets you specify record formats that are com- 
patible with files created by other language processors. You can choose 
one of four qualifiers: LIST, FORTRAN, ANY, and NONE. The default 
for VAX BASIC is LIST, which specifies carriage return format. This is 
standard for ASCII text files and means that carriage control is performed 
by RMS when writing the file to a unit-record device. 


If your program accesses a file created with a FORTRAN language proces- 
sor, use the FORTRAN qualifier. In the following example, the FORTRAN 
qualifier sets the FORTRAN carriage control attribute in the RAT field 

in the FAB. For more information on the FAB control structure, see 
Section 15.8.11. The first byte of the record is assumed to be the carriage 
control information. 


OPEN "FIL.DAT" FOR INPUT AS FILE #1%, & 
ORGANIZATION SEQUENTIAL, RECORDTYPE FORTRAN 


If your program accesses a file created by an unknown language processor 
or by DCL, use the ANY qualifier; this qualifier causes VAX BASIC 

to handle any record attribute type. If you create a file with the ANY 
qualifier, VAX BASIC uses the default of LIST. 


OPEN "FIL.DAT" FOR INPUT AS FILE #1%, & 
ORGANIZATION INDEXED, RECORDTYPE ANY 


15.8.10 The TEMPORARY Clause 


If you specify the TEMPORARY clause in the OPEN statement, VAX 
BASIC deletes that file in any one of the following cases: 


e When you close the file 
e When the program aborts or exits 
e¢ When your process terminates 


No entry for this file is made in any directory. 
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15.8.11 The USEROPEN Clause 


The USEROPEN clause specifies an external long function that VAX 
BASIC executes when you open or create a file. (You do not need to de- 
clare the USEROPEN routine with an EXTERNAL FUNCTION statement.) 
This procedure can then specify additional OPEN parameters for the file. 
For example: 


OPEN "FILE.DAT" FOR INPUT AS FILE #2%, & 
ORGANIZATION INDEXED, USEROPEN Myopen, MAP ABC 


The code in Myopen determines how the file FILE.DAT is opened. The 
Run-Time Library sets up six RMS control structures before calling the 
USEROPEN procedure. Table 15-4 defines these structures and their 
meanings. 


Table 15-4: VAX RMS Control Structures Set for the 
USEROPEN Clause 


FAB File Access Block 

RAB Record Access Block 

NAM Name Block 

XAB FHC Extended Attributes Block 
ESA Expanded Name String 

RSA Resultant Name String 


A USEROPEN procedure should not alter the allocation of these struc- 
tures, although it can modify the contents of many of the fields. You 

should not modify fields set by other OPEN statement keywords. For 
example, you should use the RECORDSIZE clause, not a USEROPEN 

routine, to set the record length. 


The allocation of the RMS control structures (except for the RAB) lasts only 
for the duration of the OPEN statement. Therefore, your USEROPEN can 
retain only the RAB address for use after the OPEN operation is complete. 
Note that any additional structures that you allocate and link into the 
RMS structures must be unlinked before exiting the USEROPEN. 


NOTE 


Future releases of the Run-Time Library may alter the use of 
some VAX RMS fields. Therefore, you may have to alter your 
USEROPEN procedures accordingly. 
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The following steps describe the execution of the USEROPEN routine: 


1. VAX BASIC performs normal OPEN statement processing up to the 
point where it would call the RMS OPEN/CREATE and CONNECT 
routines. VAX BASIC then passes control to the USEROPEN routine. 


2. VAX BASIC passes the address of the FAB as the first parameter, the 
address of the RAB as the second parameter, and the address of the 
user-specified channel number as the third parameter to the routine. 


3. The USEROPEN routine can modify the contents of the RMS control 
structures, and it must call the RMS OPEN or RMS CREATE routine 
and the RMS CONNECT routine and return the status in RO. 


The following program creates a USEROPEN routine to obtain a RAB 
address. 


Example 


“TITLE “Example USEROPEN" 
“SBTTL "Useropen Routine to obtain RAB address" 
%IDENT “Version 1.0" 


FUNCTION LONG Get_rab_address ( Fabdef User_fab, Rabdef User_rab, LONG Channel ) 
++ 


! FUNCTIONAL DESCRIPTION: 
! 


Save the address of the RMS Record Access Block allocated by the caller 
in a global symbol. Open the file and return the status from RMS. 


! 
! 
{ 
! FORMAL PARAMETERS (Standard for all BASIC USEROPEN procedures) 
t 

! User_fab Address of RMS File Access Block 

! User_rab Address of RMS Record Access Block 

! Channel Logical Unit assigned to file by caller. 

! 

! 

! 

! 

! 

! 

t 

{- 


RETURN VALUE: RMS Status value 


GLOBAL COMMON USAGE 


RAB_ptr Single longword PSECT used to pass RAB address to caller. 
OPTION INACTIVE = SETUP, & 
CONSTANT TYPE = INTEGER, & 


TYPE = EXPLICIT 


YNOLIST 

“INCLUDE "$FABDEF" %FROM %LIBRARY "SYS$LIBRARY : BASIC$STARLET" 
“INCLUDE "$RABDEF" %FROM LIBRARY "SYS$LIBRARY : BASIC$STARLET" 
%INCLUDE "$RMSDEF" %FROM %LIBRARY "SYS$LIBRARY : BASIC$STARLET" 
%INCLUDE "STARLET" %FROM %LIBRARY "SYS$LIBRARY : BASIC$STARLET" 
Y%LIST 
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I+ 
! Common area used to pass RAB address to caller. 
{- 


COMMON (RAB_ptr) LONG rab_address 

DECLARE LONG Rns_status 

1+ 

! Save RAB address in global symbol known to caller. 


! Perform standard RMS open sequence 
f- 


Rab_address = LOC(User_rab: :rab$b_bid) 
Rms_status = Sys$open( User_fab ) 


IF Rms_status AND Rms$_normal 
THEN 

Rms_status = Sys$connect( User_rab ) 
END IF 


END FUNCTION Rms_status 


NOTE 


You cannot use a USEROPEN routine to fill the RBF, UBF, 
BKS, or CTX fields in the RAB. These fields are filled in after 
the USEROPEN routine returns; any values placed there by 
the USEROPEN routine are overwritten. Also, you must not 
set RMS Locate mode when using a USEROPEN routine on 
sequential files. 


15.8.12 The WINDOWSIZE Clause 


The WINDOWSIZE clause specifies the number of block retrieval pointers 
in memory for the file. WINDOWSIZE is not a file attribute, and therefore 
can be changed any time you open a file. 


Retrieval pointers are associated with the file header and point to con- 
tiguous blocks on disk. By keeping retrieval pointers in memory, you can 
reduce the I/O associated with locating a record because the operating 
system does not have to access the file header for pointers as frequently. 
The number of retrieval pointers in memory at any one time is determined 
by the system default or by the value you supply in the WINDOWSIZE 
clause. The usual default number of retrieval pointers is 7. 


A value of zero specifies the default number of retrieval pointers. A value 
of 255 specifies mapping the entire file, if possible. Values between 128 
and 254 inclusive are reserved. 
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Chapter 16 


Formatting Output with the PRINT USING 
Statement 


The PRINT USING statement controls the appearance and location of data 
on a line of output. With it, you can create formatted lists, tables, reports, 
and forms. This chapter describes how to format data with the PRINT 
USING statement. 


16.1 Introduction 


The ability to format data with the PRINT USING statement is useful 
because the way in which VAX BASIC displays data with the PRINT 
statement is often limited. For example, a program may use floating-point 
numbers to represent dollars and cents. The PRINT statement displays 
floating-point numbers with up to six digits of accuracy, and places the 
decimal point anywhere in that 6-digit field. In contrast, PRINT USING 
lets you display floating-point numbers in the following ways: 


¢ Rounded to two decimal places 

e Vertically aligned on the decimal point 

e Preceded by a dollar sign 

e With commas every third digit to the left of the decimal point 


Formatting monetary values in this way provides a much more readable 
report. Another use for formatted numeric values might be to print checks 
on a line printer. PRINT USING lets you print numbers with a dollar sign 
and an asterisk-filled field preceding the first digit. 
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PRINT USING also formats string data. With it you can left- and right- 
justify string expressions, or center a string expression over a specified 
column position. Further, the PRINT USING statement can contain string 
literals. These are strings that do not control the format of a print item, 
but instead are printed exactly as they appear in the format string. 


DIGITAL recommends that you declare all format expressions as string 
constants. When you do this the VAX BASIC compiler causes the Run- 
Time Library to compile the string at compile time rather than at run time, 
thus improving the performance of your code. 


16.2 Using Format Strings 


Format strings determine the way in which items are to be printed in the 
output file. Format strings can be any of the following: 


e String variables 

e String literals 

e Named string constants 

e A combination of the above 


The PRINT USING statement must contain one or more format strings. 
Each format string is made up of one format field. Each format field con- 
trols the output of one print item and can contain only certain characters, 
as described throughout the chapter. 


The PRINT USING statement must also contain a list of items you want 
printed. To format print items, you must separate them with commas or 
semicolons. Separators between print items do not affect output format as 
they do with the PRINT statement. However, if a comma or semicolon 
follows the last print item, VAX BASIC does not return the cursor or print 
head to the beginning of the next line after it prints the last item in the 
list. 


When VAX BASIC encounters an invalid character within the current 
format field, it automatically ends the format field. Therefore, you do not 
need to delimit format fields. The character that terminates the previous 
field can be either a new format field or a string literal. 


In the following example, the first three characters in the format string 
(###) make up a valid numeric format field. The fourth character (A) 
is invalid in a numeric format field; therefore, VAX BASIC ends the first 
format field after the third character. VAX BASIC continues to scan the 
format string, searching for a character that begins a format field. The 
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first such character is the number sign at character position 7. Therefore, 
the characters at positions 4, 5, and 6 are treated as a string literal. The 
characters at positions 7, 8, and 9 make up a second valid numeric format 
field. 


Example 
PRINT USING "###ABC###", 123, 345 


Output 
123ABC345 


When the statement executes, VAX BASIC prints the first number in the 
list using the first format field, then prints the string literal ABC, and 
finally prints the second number in the list using the second format field. 
If you were to supply a third number in the list, VAX BASIC would reuse 
the first format string. This is called reversion. 


Example 

PRINT USING "###ABC###", 123, 345, 
564 

Output 


123ABC345 
564ABC 


Because any character not part of a format field is printed just as it appears 
in the format field, you can use a space or multiple spaces to separate 
format fields in the format string as shown in the following example. 


Example 


DECLARE STRING CONSTANT format_string = "###.##  #i#. ##" 
DECLARE SINGLE A,B 

A = 2.565 

B = 100.350 

PRINT USING format_string, A, B, A, B 


Output 


2.57 100.35 
2.57 100.35 
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When the VAX BASIC compiler encounters the PRINT USING statement, 
VAX BASIC prints the value of A (rounded according to PRINT USING 
rules), three spaces, then the value of B. VAX BASIC prints the three 
spaces because they are treated as a string literal in the format string. 
Notice that when VAX BASIC reuses a format string, it begins on a new 
line. 


16.3 Printing Numbers 


With the PRINT USING statement, you can specify: 
e The number of digits to print, thus rounding the number to a given 
place 


e The decimal point location, thus vertically aligning numbers at the 
decimal point 


¢ Special symbols, including trailing minus signs, asterisk-filled number 
fields, floating currency symbols, embedded commas, and E notation 


e Debits and credits 

e Leading zeros or leading spaces 

e Blank-if-zero fields 

e A special character that is to be printed as a literal 


Unlike the PRINT statement, PRINT USING does not automatically print 
a space before and after a number. Unless you reserve enough digit 
positions to contain the integer portion of the number (and a minus sign, 
if necessary), VAX BASIC prints a percent sign (%) to signal this condition 
and displays the number in PRINT format. 


16.3.1 Specifying the Number of Digits 


You reserve places for digits by including a number sign (#) for each digit 
position. If you print negative numbers, you must also reserve a place for 
the minus sign. 
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Example 


PRINT USING "###" 123 !Three places reserved 
PRINT USING "#####",12345 !Five places reserved 
PRINT USING "####" , -678 !Four places reserved 
END 


Output 


123 
12345 
-678 


If there are not enough digits to fill the field, VAX BASIC prints spaces 
before the first digit. 


Example 


format_string$ = "#####" 

PRINT USING format_string$, 1 
PRINT USING format_string$, 10 
PRINT USING format_string$, -1709 
PRINT USING format_string$, 12345 
END 


Output 


1 

10 
-1709 
12345 


If you have not reserved enough digits to print the fractional part of a 
number, VAX BASIC rounds the number to fit the field. 


Example 


PRINT USING "###", 126.7 
PRINT USING "#",5.9 
PRINT USING "#",5.4 

END 


Output 


127 
6 
5 


If you have not reserved enough places to print a number's integer 
portion, VAX BASIC prints a percent sign as a warning followed by the 
number in PRINT statement format. After VAX BASIC prints the number, 
it completes the rest of the list in PRINT USING format. 
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In the following example, PRINT USING displays the first number. 
Because there are not enough places to the left of the decimal point to 
display a 3-digit number, VAX BASIC prints the second number in PRINT 
statement format, with a space before and after, but includes a percent 
sign warning. 


Example 


PRINT USING "###", 256 
PRINT USING "##", 256 
END 


Output 


256 
4%, 256 


16.3.2 Specifying Decimal Point Location 


The decimal point’s position in the format string determines the number 
of reserved places on either side of it. If the print item’s fractional part 

does not use all of the reserved places to the right of the decimal point, 
VAX BASIC fills the remaining spaces with zeros. 


Example 


DECLARE STRING CONSTANT FM = "##. ###" 
PRINT USING FM, 15.72 

PRINT USING FM, 39.3758 

PRINT USING FM, 26 


Output 


15.720 
39.376 
26 .000 


If there are more fractional digits than reserved places to the right of the 
decimal point, VAX BASIC rounds the number to fit the reserved places. 
Note that there must be enough places reserved to the left of the decimal 
point for the integer portion of the number. Otherwise, VAX BASIC prints 
the number in PRINT format preceded by a percent sign. The following 
example shows how PRINT USING rounds numbers when you specify 
decimal point location. 
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Example 


PRINT USING "##.##", 25.789 
PRINT USING "##.###", 100.2 
PRINT USING "#.##", .999 

END 


Output 


25.79 
% 100.2 
1.00 


VAX BASIC fills all reserved spaces to the left of the decimal point with 
specified digits, spaces, or the minus sign. 


Example 


PRINT USING "##.##", 5.25 

PRINT USING "##.##", -5.25 
PRINT USING "###.##,-5.25 

END 


Output 


5.25 
-5.25 
-5.25 


16.3.3 Printing Numbers with Special Symbols 
Special symbols let you print numbers with trailing minus signs, asterisk- 
fill fields, floating currency symbols, commas, or E notation. You can also 


specify debits, credits, leading zeros, leading blanks, and blank-if-zero 
fields. Table 16-1 summarizes these special characters. 
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Table 16—1: Format Characters for Numeric Fields 


Character 
Number sign (#) 
Decimal point (period) (.) 


Comma (,) 


Two asterisks (**) 


Two dollar signs ($$) 


Four carets (~*") 


Minus sign (-) 


Zero in angle brackets ( <0> ) 
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Effect on Format 
Reserves a place for one digit. 


Determines decimal point location 
and reserves a place for the radix 
point. 


Prints a comma before every third 
digit to the left of the decimal point 
and reserves a place for one digit or 
digit separator. 


Print leading asterisks before the 
first digit and reserve places for two 
digits. 

Print a currency symbol before 

the first digit. They also reserve 
places for the currency symbol 

and one digit. By default, the 
currency symbol is a dollar sign. To 
change the currency symbol, see 
Section 16.3.3.3. 


Print a number in E (exponential) 
format and reserve four places for E 
notation. 


Prints a trailing minus sign for 
negative numbers. Printing a 
negative number in an asterisk-fill 
or a currency field requires that the 
field also have a trailing minus sign 
or credit/debit character. 


Prints leading zeros instead of 
leading spaces. 


Table 16-1 (Cont.): Format Characters for Numeric Fields 
Character Effect on Format 


Percent sign in angle brackets ( <%> ) Prints all spaces in the field if 
the value of the print item, when 
rounded to fit the numeric field, is 
zero. 


CD in angle brackets ( <CD> ) Prints credit and debit characters 
immediately following the number. 
VAX BASIC prints CR for negative 
numbers and zero, and DR for 
positive numbers. 


Underscore (_) Specifies that the next character is a 
literal, not a formatting character. 


16.3.3.1 Commas 


You can place a comma anywhere in a number field to the left of the 
decimal point or to the right of the field’s first character. A comma cannot 
start a format field. VAX BASIC prints a comma to the left of every third 
digit from the decimal point. If there are fewer than four digits to the left 
of the decimal point, VAX BASIC omits the comma. 


Example 


PRINT USING "##, ###" , 10000 
PRINT USING "##, ###" ,759 

PRINT USING "$$#, ###.##" ,25694.3 
PRINT USING "**#, ###" ,7259 
PRINT USING "####,#.##" , 25239 
END 


Output 


10,000 
759 

$25,694.30 

**7 , 259 

25 , 239.00 
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16.3.3.2 Asterisk-Fill Fields 


To print asterisks (*) before the first digit of a number, you must start the 
field with two asterisks. 


Example 


DECLARE STRING CONSTANT FM = "*+*##. ##" 
PRINT USING FM, 1.2 

PRINT USING FM, 27.95 

PRINT USING FM, 107 

PRINT USING FM, 1007.5 

END 


Output 


**#1,20 
**27 .95 
*107.00 
1007.50 


Note that the asterisks reserve two places as well as cause asterisk fill. 


To specify a negative number in an asterisk-fill field, you must place a 
trailing minus sign in the field. The trailing minus sign must be the last 
character in the format string. 


Example 


DECLARE STRING CONSTANT FM = "**##.##-" 
PRINT USING FM, 27.95 

PRINT USING FM, -107 

PRINT USING FM, -1007.5 

END 


Output 


**27 .95 
*107 .00- 
1007 .50- 


If you try to print a negative number in an asterisk-fill field that does not 
include a trailing minus sign, VAX BASIC signals “PRINT USING format 
error” (ERR = 116). 


You cannot specify both asterisk-fill and zero-fill for the same numeric 
field. 
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16.3.3.3 Currency Symbols 


To print a currency symbol before the first digit of a number, you must 
start the field with two dollar signs. If the data contains both positive and 
negative numbers, you must include a trailing minus sign. 


Example 


DECLARE STRING CONSTANT FM = "$$##.##-" 
PRINT USING FM, 77.44 

PRINT USING FM, 304.55 

PRINT USING FM, 2211.42 

PRINT USING FM, -125.6 

PRINT USING FM, 127.82 

END 


Output 


$77.44 
$304.55 
% 2211.42 
$125 .60- 
$127.82 


Note that the dollar signs reserve places for the currency symbol and only 
one digit; the dollar sign is always printed. (Hence the warning indicator 
(% ) when the third PRINT USING statement executes.) Contrast this 
with the asterisk-fill field, where VAX BASIC prints asterisks only when 
there are leading spaces. 


By default, the currency symbol is a dollar sign. On VAX/VMS systems, 
you can change the currency symbol, radix point, and digit separator by 
assigning the characters you want to the logical names SYS$CURRENCY, 
SYS$RADIX_POINT, and SYS$ DIGIT_SEP, respectively. 


If you try to print a negative number in a dollar sign field that does not 
include either a trailing minus sign or the CR/DR formatting character, 
VAX BASIC signals “PRINT USING Format error” (ERR = 116). 
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16.3.3.4 Negative Fields 


To allow for a field containing negative values, you must place a trailing 
minus sign in the format field. A negative format field causes the value to 
be printed with a trailing minus sign. You can also denote negative fields 
with CR and DR. See Section 16.3.3.8 for more information. 


You must use a trailing minus or the CR/DR formatting character to 
indicate a negative number in an asterisk-fill or floating dollar sign field. 


For fields with trailing minus signs, VAX BASIC prints a minus sign after 
negative numbers as shown in Example 1, and a space after positive 
numbers as shown in Example 2: 


Example 1 


!Standard field 
PRINT USING "###.##" ,-10.54 
PRINT USING "###.##",10.54 
END 
Output 1 
-10.54 
10.54 
Example 2 


!Fields with Trailing Minus Signs 
PRINT USING "##.##-",-10.54 

PRINT USING "##.##-",10.54 

END 

Output 2 


10.54- 
10.54 


16.3.3.5 E (Exponential) Format 


To print a number in E format, you must place four carets (“*"") at the end 
of the field. The carets reserve space for: 


¢ The capital letter E 
e A plus or minus sign (which indicates a positive or negative exponent) 


e An exponent (the exponent is 2 digits for single and double, 3 digits 
for G_floating and 4 digits for H_floating) 
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In exponential format, VAX BASIC does not pad the digits to the left 

of the decimal point. Instead, the most significant digit shifts to the 
leftmost place of the format field, and the exponent compensates for this 
adjustment. 


Example 


PRINT USING "###.##°°°°",5 
PRINT USING "###.##°"""", 1000 
PRINT USING ".##°°""",5 

END 


Output 


500 .O0E-02 
100 .OOE+01 
.50E+01 


If you use fewer than four carets, the number does not print in E format; 
the carets print as literal characters. If you use more than four carets, VAX 
BASIC prints the number in E format and includes the extra carets as a 
string literal. 


Example 


PRINT USING "###.##°""",5 
PRINT USING "###.##°°""° ",5 
END 


Output 


5.00°°~ 
500 .00E-02~ 


You must reserve a place for a minus sign to the left of the decimal point 
to display negative numbers in exponential format. If you do not, VAX 
BASIC prints a percent sign (%) as a warning. 


You cannot use exponential format with asterisk-fill, floating dollar sign, 
or trailing minus formats. 
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16.3.3.6 Leading Zeros 
To print leading zeros in a numeric field, you must start the format field 
with a zero enclosed in angle brackets (<0> ). These characters also 
reserve one place for a digit. 
Example 
DECLARE STRING CONSTANT FM = "<O>####.##" 
PRINT USING FM, 1.23, 12.34, 123.45, 1234.56, 12345.67 
Output 


00001 . 23 
00012 .34 
00123 .45 
01234 .56 
12345 .67 


When you specify zero-fill, you cannot specify asterisk-fill or floating- 
dollar sign format for the same field. 


16.3.3.7 Blank-Iif-Zero Fields 


To make VAX BASIC print a blank field for values which round to zero, 
you must start the numeric field with a percent sign (% ) enclosed in angle 
brackets (<%> ). 


In the following example, PRINT USING displays spaces in each reserved 
position for the second and third items in the list. The value of the second 
item is zero, while the value of the third item becomes zero when rounded 
to fit the numeric field. 

Example 


DECLARE STRING CONSTANT FM = "<{>###e.##" 
PRINT USING FM, 1000, 0, .001, -5000 


Output 
1000.00 


-5000 
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16.3.3.8 Debits and Credits 


You can have VAX BASIC use credit and debit notation to differentiate 
positive and negative numbers. To do this, you place the characters 
<CD> (Credit/Debit) at the end of the numeric format string. This 
causes VAX BASIC to print CR (Credit Record) after negative numbers, 
and DR (Debit Record) after positive numbers and zero. 


Example 

DECLARE STRING CONSTANT FM = "$$####.##<cd>" 
PRINT USING FM, -552.35, 200, -5 

Output 


$552. 35CR 
$200. O0DR 
$5. 0OCR 


You cannot use a trailing minus sign and Credit/Debit formatting in the 
same numeric field. Using the Credit/Debit formatting character causes 
the value to be printed with a leading space. 


16.4 Printing Strings 


With the PRINT USING statement, you can specify the following aspects 
of string format: 


e The number of characters 
e = Left-justified format 

¢  Right-justified format 

e Centered format 

e Extended field format 


Table 16-2 summarizes the format characters and their effects. 
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Table 16-2: Format Characters for String Fields 


Character 


Single quotation mark (') 
L (upper- or lowercase) 
R (upper- or lowercase) 
C (upper- or lowercase) 


E (upper- or lowercase) 


Two backslashes (\ \) 


Exclamation point (!) 


Effect on Format 


Starts the string field and reserves a place for 
one character. 


Left-justifies the string and reserves a place for 
one character. 


Right-justifies the string and reserves a place for 
one character. 


Centers the string in the field and reserves a 
place for one character. 


Left-justifies the string; expands the field, 
as necessary, to print the entire string; and 
reserves a place for one character. 


Reserves n+2 character positions, where n is the 
number of spaces between the two backslashes. 
PRINT USING left-justifies the string in this 
field. This formatting character is included 

for compatibility with BASIC-PLUS. DIGITAL 
recommends that you do not use this type of 
field for new program development. 


Creates a one-character field. The exclamation 
point both starts and ends the field. This 
formatting character is included for compatibility 
with BASIC-PLUS. DIGITAL recommends that 
you do not use this type of field for new 
program development. Instead, use a single 
quotation mark to create a one-character field. 


You must start string format fields with a single quotation mark (’) that 
reserves a space in the print field, followed by: 


e A contiguous series of upper- or lowercase Ls for left-justified output 


e A contiguous series of upper- or lowercase Rs for right-justified output 


e A contiguous series of upper- or lowercase Cs for centered output 


e A contiguous series of upper- or lowercase Es for extended field output 
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VAX BASIC ignores the overflow of strings larger than the string format 

field except for extended fields. For extended fields, VAX BASIC extends 
the field to print the entire string. If a string to be printed is shorter than 
the format field, VAX BASIC pads the string field with spaces. For more 

information on extended fields, see Section 16.4.4. 


A string field containing only a single quotation mark is a one-character 
string field. VAX BASIC prints the first character of the string expression 
corresponding to a one-character string field and ignores all following 
characters. 

Example 

PRINT USING "'*,"ABCDE" 

END 

Output 

A 


See Section 16.4.4 for an example of many different types of fields used 
together. 


16.4.1 Left-Justified Format 


VAX BASIC prints strings in a left-justified field starting with the left-most 
character. VAX BASIC pads shorter strings with spaces and truncates 
longer strings on the right to fit the field. 


A left-justified field contains a single quotation mark followed by a series 
of Ls. 


Example 


PRINT USING "'LLLLLL" , “ABCDE" 
PRINT USING "'LLLL", "ABC" 
PRINT USING "'LLLLL", "12345678" 
END 


Output 


ABCDE 
ABC 
123456 
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16.4.2 Right-Justified Format 


VAX BASIC prints strings in a right-justified field starting with the right- 
most character. VAX BASIC pads the left side of shorter strings with 
spaces. If a string is longer than the field, VAX BASIC left-justifies and 
truncates the right side of the string. 


A right-justified field contains a single quotation mark (‘) followed by a 
series of Rs. 


Example 


DECLARE STRING CONSTANT right_justify = "'RRRRR" 
PRINT USING right_justify, "ABCD" 

PRINT USING right_justify,"A" 

PRINT USING right_justify, "STUVWXYZ" 

END 


Output 


ABCD 
A 
STUVWX 


16.4.3 Centered Fields 


VAX BASIC prints strings in a centered field by aligning the center of the 
string with the center of the field. If VAX BASIC cannot exactly center 

the string—as is the case for a 2-character string in a 5-character field, for 
example—VAX BASIC prints the string one character off center to the left. 


A centered field contains a single quotation mark followed by a series 
of Cs. 
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Example 


DECLARE STRING CONSTANT center = "'CCCC" 
PRINT USING center, "A" 

PRINT USING center, "AB" 

PRINT USING center, "ABC" 

PRINT USING center, "ABCD" 

PRINT USING center, "ABCDE" 

END 


Output 


A 
AB 
ABC 

ABCD 
ABCDE 


If there are more characters than places in the field, VAX BASIC left- 
justifies and truncates the string on the right. 


16.4.4 Extended Fields 


An extended field contains a single quotation mark followed by one or 
more Es. The extended field is the only field that automatically prints the 
entire string. In addition: 


e If the string is smaller than the format field, VAX BASIC left-justifies 
the string as in a left-justified field. 


e If the string is longer than the format field, VAX BASIC extends the 
field and prints the entire string. 
Example 


PRINT USING "'E", "THE QUICK BROWN" 
PRINT USING "‘EEEEEEE', "FOX" 
END 


Output 


THE QUICK BROWN 
FOX 


The following example uses left-justified, right-justified, centered, and 
extended fields. 
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Example 


PRINT USING "'LLLLLLLLL" ,"THIS TEXT" 

PRINT USING "'LLLLLLLLLLLLLL" ,"SHOULD PRINT" 

PRINT USING "'LLLLLLLLLLLLLL", 'AT LEFT MARGIN' 

PRINT USING "'RRRR","1,2,3,4" 

PRINT USING "'RRRR",'1,2,3' 

PRINT USING "'RRRR',"1,2" 

PRINT USING "'RRRR","1" 

PRINT USING "'CCCCCCCCC","A" 

PRINT USING "'CCCCCCCCC" , "ABC" 

PRINT USING "'CCCCCCCCC" , "ABCDE" 

PRINT USING "'CCCCCCCCC", "ABCDEFG" 

PRINT USING "'CCCCCCCCC", "ABCDEFGHI" 

PRINT USING "'LLLLLLLLLLLLLLLLL' ,"YOU ONLY SEE PART OF THIS" 
PRINT USING "‘E","YOU CAN SEE ALL OF THE LINE WHEN IT IS EXTENDED" 
END 


Output 


THIS TEXT 
SHOULD PRINT 
AT LEFT MARGIN 
1,2, 
1,2 
1 


Pre wD Ww & 


ABC 
ABCDE 
ABCDEFG 
ABCDEFGHI 
YOU ONLY SEE PART 
YOU CAN SEE ALL OF THE LINE WHEN IT IS EXTENDED 


16.5 PRINT USING Statement Error Conditions 


There are two types of PRINT USING error conditions: fatal and warning. 
VAX BASIC signals a fatal error if 


e The format string is not a valid string expression 
e There are no valid fields in the format string 

¢ You specify a string for a numeric field 

e You specify a number for a string field 


e You separate the items to be printed with characters other than 
commas or semicolons 
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e 6A format field contains an invalid combination of characters 


e You print a negative number in a floating dollar sign or asterisk-fill 
field without a trailing minus sign 


VAX BASIC issues a warning if a number does not fit in the field. If a 
number is larger than the field allows, VAX BASIC prints a percent sign 
(%) followed by the number in the standard PRINT format and continues 
execution. 


If a string is larger than any field other than an extended field, VAX BASIC 
truncates the string and does not print the excess characters. 


If a field contains an invalid combination of characters, VAX BASIC does 
not recognize the first invalid character or any character to its right as 
part of the field. These characters may form another valid field or be 
considered text. If the invalid characters form a new valid field, a fatal 
error condition may arise if the item to be printed does not match the 
field. 


The following examples demonstrate invalid character combinations in 
numeric fields. 


Example 1 
PRINT USING "$$*+##.##" ,5.41,16.30 


The dollar signs form a complete field and the rest forms a second valid 
field. The first number (5.41) is formatted by the first valid field ($$). It 
prints as “$5”. The second number (16.30) is formatted by the second field 
(**##.##) and prints as “**16.30”. 


Output 1 
$5**16.30 


Example 2 
PRINT USING "##.#°77",5.43E09 


Because the field has only three carets instead of four, VAX BASIC prints 
a percent sign and the number, followed by three carets. 


Output 2 
% .543E+107*~ 
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Example 3 

PRINT USING "'LLEEE", "VWXYZ" 

You cannot combine two letters in one field. VAX BASIC interprets EEE 
as a String literal. 

Output 3 

VWXEEE. 
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Chapter 17 
Handling Run-Time Errors 


The process of detecting and correcting errors that occur when your 
program is running is called error handling. This chapter describes default 
error handling and how to handle VAX BASIC run-time errors with your 
own error handlers. 


Throughout this chapter, the term error is used to imply any VAX/VMS 
exception, not only an exception of ERROR severity. 


17.1 Default Error Handling 


VAX BASIC provides default run-time error handling for all programs. If 
you do not provide your own error handlers, the default error handling 
procedures remain in effect throughout program execution time. 


When an error occurs in your program, VAX BASIC diagnoses the error 
and displays a message telling you the nature and severity of the error. 
There are four severity levels of VAX BASIC errors: SEVERE, ERROR, 
WARNING, and INFORMATIONAL. The severity of an error determines 
whether or not the program aborts if the error occurs when default error 
handling is in effect. When default error handling is in effect, ERROR 
and SEVERE errors always terminate program execution, but program 
execution continues when WARNING and INFORMATIONAL errors 
occur. 


To override the default error handling procedures, you can provide your 
own error handlers, as described in the following sections. (Note that you 
should not call LIBSESTABLISH from a VAX BASIC program as this RTL 
routine overrides the default error handling procedures and may adversely 
affect program behavior.) 
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Only one error can be handled at a time. If an error has occurred but has 
not yet been handled completely, that error is said to be pending. When 
an error is pending and a second error occurs, program execution always 
terminates immediately. Therefore, one of the most important functions of 
an error handler is to clear the error so that subsequent errors can also be 
handled. 


If you do not supply your own error handler, program control passes 

to the VAX BASIC error handler when an error occurs. For instance, 
when VAX BASIC default error handling is in effect, a program will abort 
when division by zero is attempted because division by zero is an error of 
SEVERE severity. With an error handler, you can include an alternative 
set of instructions for the program to follow; if the zero was input at a 
terminal, a user-written error handler could display a “Try again” message 
and reexecute the program lines requesting input. 


17.2 User-Supplied Error Handlers 


It is good programming practice to anticipate certain errors and provide 
your own error handlers for them. User-written error handlers allow you 
to handle errors for a specified block of program statements as well as 
complete program units. Any program module can contain one or more 
error handlers. These error handlers test the error condition and include 
statements to be executed if an error occurs. 


To provide your own error handlers, you use WHEN ERROR constructs. 
A WHEN ERROR construct consists of two blocks of code: a protected 
region and a handler. A protected region is a block of code that is mon- 
itored by the compiler for the occurrence of an error. A handler is the 
block of code that receives program control when an error occurs during 
the execution of the statements in the protected region. 


There are two forms of WHEN ERROR constructs; in both cases the 
protected region begins immediately after a WHEN ERROR statement. 
The following partial programs illustrate each form. In Example 1, the 
handler is attached to the protected region, while in Example 2, the 
handler catch_handler is detached and must be provided elsewhere in the 
program unit. 
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Example 1 


WHEN ERROR IN 
protected_statement_1 
protected_statement_2 


USE 
handler_statement_i 
handler_statement_2 


END WHEN 


Example 2 


WHEN ERROR USE catch_handler 
protected_statement_1 
protected_statement_2 


END WHEN 


HANDLER catch_handler 
handler_statement_1 
handler_statement_2 


END HANDLER 


The following sections further explain the concepts of protected regions 
and handlers. 


17.2.1 Protected Regions 


A protected region is a block of code that is monitored by the compiler 
for the occurrence of an error. The bounds of this region are determined 
by the actual ordering of the source code. Statements that are lexically 
between a WHEN ERROR statement and a USE or END WHEN statement 
are in the protected region. 


If an error occurs inside the protected region, control passes to the error 
handler associated with the WHEN ERROR statement. When an error 
occurs beyond the limits of a protected region, default error handling is 
in effect unless other error handlers are provided. For more details about 
handler priorities, see Sections 17.2.3 and 17.3. 
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The WHEN ERROR statement signals the start of a block of protected 
statements. The WHEN ERROR statement also specifies the handler to be 
used for any errors that occur inside the protected region. The keyword 
USE either explicitly names the associated handler for the protected 
region, or marks the start of the actual handler statements. The statements 
in the actual error handler receive control only if an error occurs in the 
protected region. 


The following example prompts the user for two integer values and 
displays their sum. The WHEN ERROR block traps any invalid input 
values, displays a message telling the user that the input was invalid, and 
reprompts the user for input. 


DECLARE INTEGER value_1, value_2 


WHEN ERROR IN 
INPUT "PLEASE INPUT 2 INTEGERS"; value_1, value_2 !protected statement 


USE 
PRINT "INVALID INPUT - PLEASE TRY AGAIN" !handler statement 
RETRY thandler statement 
END WHEN 


PRINT "THEIR SUM IS"; value_i + value_2 


Protected regions can be nested; a protected region can be within the 
bounds of another protected region. However, WHEN ERROR statements 
cannot appear inside an error handler, and protected regions cannot cross 
over into other block structures. If you are using a WHEN ERROR block 
with a detached handler, that handler cannot exist within a protected 
region. 


17.2.2 Handlers 


A handler is the block of code containing instructions to be executed only 
when an error occurs during the execution of statements in the protected 
region. When an error occurs during the execution of a protected region, 
VAX BASIC branches to the handler you have supplied. In turn, the 
handler processes the error. An error handler typically performs the 
following functions: 


e Determines which error occurred 
¢ Takes appropriate action based on the nature of the error 


e §6Clears the error condition with a RETRY, CONTINUE, END WHEN, 
or END HANDLER statement 
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¢ Continues program execution when possible 
e Possibly identifies which program unit or statement caused the error 


e Resignals errors with EXIT HANDLER (when an error cannot be 
handled for some reason) 


Handlers can be attached to, or detached from, the statements in the 
WHEN ERROR protected region. 


An attached handler is delimited by a USE and an END WHEN statement. 
The attached handler immediately follows the protected region of a 
WHEN ERROR IN block. The following example illustrates an attached 
handler that traps errors on I/O statements, division by zero and illegal 
numbers. 


Example 


PROGRAM accident_prone 

DECLARE REAL age, accidents, rating 

WHEN ERROR IN 

Get_age: 

INPUT "Enter your age" ;age 
INPUT "How many serious accidents have you had" ;accidents 
rating = accidents/age 
PRINT "That's ";rating;" serious accidents per year!" 


USE 
SELECT ERR 
!Trap division by zero 
CASE = 61 
PRINT "Please enter an age greater than 0" 
CONTINUE Get_age 


!Trap illegal number 
CASE = 52 
PRINT "Please enter a positive nunber" 
RETRY 
CASE ELSE 
!'Revert to default error handling 
EXIT HANDLER 
END SELECT 
END WHEN 
END PROGRAM 


A detached handler is defined separately in your program unit. It re- 
quires an identifier and must be delimited by a HANDLER and an END 
HANDLER statement. Handler names must be valid VAX BASIC identi- 
fiers and cannot be the same as the identifier for any label, PROGRAM 
name, DEF or DEF* function, SUB, FUNCTION, or PICTURE subprogram. 
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The main advantage of using a detached handler is that it can be refer- 
enced by more than one WHEN ERROR USE statement. The following 
example illustrates a simple detached handler: 


Example 
WHEN ERROR USE catcher 
KILL "INPUT.DAT" 
END WHEN 


HANDLER catcher 
{Catch if file does not exist 
IF ERR = 5 
THEN CONTINUE 
END IF 
END HANDLER 


The statements within a handler are never executed if an error does not 
occur or if no protected region exists for the statement that caused the 
exception. 


When your program generates an error, control transfers to the specified 
handler. If the code in an error handler generates a second error, control 
returns to the VAX BASIC error handler and program execution ends, 
usually with the first error only partly processed. To avoid the possibility 
of your error handler causing a second error, you should keep handlers as 
simple as possible and keep operations that might cause errors outside the 
handler. 


Your handler can include conditional expressions to test the error and 
branch accordingly, as shown in the following example: 


Example 


PROGRAM Check_records 
WHEN ERROR USE Global_handler 


END WHEN 
HANDLER Global_handler 
SELECT ERR 
!Trap buffer overflow 
CASE = 161 
PRINT "Record too long" 
CONTINUE 
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!Trap end of file on device 
CASE = 11 
PRINT "End of file" 
CONTINUE Over 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END HANDLER 
Over: 
CLOSE #1% 
END PROGRAM 


Note that ON ERROR statements are not allowed within protected regions 
or handlers. For compatibility issues related to ON ERROR statements, 
see Section 17.3. 


17.2.3 Exiting from Handlers 


After processing an error, a handler typically clears the error so that 
program execution can continue. VAX BASIC provides statements that 
clear the error condition and exit from the handler: 


e RETRY 

e CONTINUE 

e END HANDLER 
e END WHEN 


These statements differ from each other in that they revert control of 
program execution to different points in the program. Examples of these 
statements are included in the following sections. 


An additional statement, EXIT HANDLER, is provided to allow you to exit 
from a handler with the error still pending. 


The END HANDLER statement identifies the end of the block of state- 
ments in the handler. The END WHEN statement marks the end of the 
protected region when a detached handler is used; it marks the end of the 
handler when an attached handler is used. If the handler does not process 
an error with an EXIT HANDLER, RETRY, or CONTINUE statement, 

the error is cleared by the END HANDLER or END WHEN statement; 
however, processing continues with the statement immediately after the 
protected region (and the attached handler, if one exists) where the error 
occurred. These statements do not return control to the protected region. 
This is known as "falling out the bottom of a handler". Be careful not to 
fall out of the bottom of a handler unintentionally. 
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Note that you cannot exit from a handler with the following statements: 


¢ EXIT PROGRAM 

e EXIT FUNCTION 

e EXIT SUB 

e EXIT DEF 

e GOSUB (with a target outside the handler) 
e GOTO (with a target outside the handler) 


Also, you cannot exit from a handler with a RESUME statement. The 
RESUME statement is valid only in blocks of code referred to by ON 
ERROR statements. Section 17.3 describes the ON ERROR statements. 


17.2.3.1 The RETRY Statement 


You use the RETRY statement to clear the error and reexecute the state- 
ment that caused the error. Be sure to take corrective action before trying 
the protected statement again. 


Example 
DECLARE REAL radius 


WHEN ERROR USE fix_it 

INPUT "Please supply the radius of the circle"; radius 
END WHEN 
HANDLER fix_it 

!trap overflow error 


IF ERR = 48 
PRINT “Please supply a smaller radius" 
RETRY 

END HANDLER 


PRINT "The circumference of the circle is "; 2*PI*radius 


In FOR...NEXT loops, if the error occurs while VAX BASIC is evaluating 
the limit or increment values, RETRY reexecutes the FOR statement; if the 
error occurs while VAX BASIC is evaluating the index variable, RETRY 
reexecutes the NEXT statement. In UNTIL...NEXT and WHILE...NEXT 
loops, if the error occurs while VAX BASIC is evaluating the relational 
expression, RETRY reexecutes the NEXT statement. 
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17.2.3.2 The CONTINUE Statement 


You can use the CONTINUE statement to clear the error and cause exe- 
cution to continue at the statement immediately following the propagated 
error. 


When the CONTINUE statement is within an attached handler, you can 
specify a target. The target can be a line number or label within the 
bounds of the associated protected region, in a surrounding protected 
region, or within an unprotected region. However, you must specify a 
target within the current program module. You cannot specify a target for 
the CONTINUE statement when it is in a detached handler. 


Example 


DIM LONG her_attributes(10) ,his_attributes(10) 
DECLARE INTEGER counter 
WHEN ERROR USE fix_it 

DATA 12,2,35,21,25.5,32,32,30,15,4 

FOR counter = O TO 12 

READ her_attributes (counter) 

NEXT counter 

MAT his_attributes = her_attributes 
END WHEN 


HANDLER fix_it 
!Trap out of data 
IF ERR = 57 

THEN RESTORE 
CONTINUE 

ELSE EXIT HANDLER 
END IF 

END HANDLER 


When a DEF function is invoked from a protected region and an error 
occurs that has not been handled, a CONTINUE statement with no 
target causes execution to resume at the statement following the one that 
invoked the function. 


Note that if an error occurs in a loop control statement or SELECT or 
CASE statement, the CONTINUE statement causes VAX BASIC to resume 
execution at the statement following the end of the loop structure (the 
NEXT, END CASE, or END SELECT statements). 


NOTE 


When you use the RETRY or the CONTINUE statement without 
a target, the compiler builds read only tables in the generated 
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object file with information about statements in the associated 
protected regions. Therefore, when space is extremely critical, 
do not protect large regions with handlers containing RETRY or 
CONTINUE without a specified target. 


17.2.3.3 The EXIT HANDLER Statement 


Unlike RETRY and CONTINUE, the EXIT HANDLER statement does not 
clear the error; rather, it allows you to exit from the handler with the 
error pending. This allows you to pass an error to the handler associated 
with the next outer protected region, or back to VAX BASIC default error 
handling, or to the calling procedure. 


When an error occurs within a nested protected region, control passes 

to the handler associated with the innermost protected region in which 
the error occurred. If the innermost handler does not handle the error, 
the error is passed to the next outer handler with the EXIT HANDLER 
statement. All handlers for any outer WHEN ERROR blocks are pro- 
cessed before reverting to default error handling or resignaling the calling 
procedure. 


The following example shows two nested protected regions. Neither 
handler traps division by zero. If division by zero occurs, the handler 
associated with the innermost protected region, inner_handler, does not 
clear the error; therefore, the error is passed to the handler associated with 
the next outer protected region. Outer_handler does not clear this error 
either, and so the error is passed to the default error handler. As this error 
is fatal, the program aborts. 


Example 


PROGRAM nesting 

OPTION TYPE = EXPLICIT 

DECLARE LONG divisor 

DECLARE REAL dividend, quotient 


WHEN ERROR USE outer_handler 
INPUT "Enter divisor" ;Divisor 
INPUT "Enter dividend"; Dividend 


WHEN ERROR USE inner_handler 
Quotient = Dividend/Divisor 
PRINT "The quotient is "; Quotient 
END WHEN 


END WHEN 
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HANDLER outer_handler 
!'Trap data format error 
IF ERR = 50 
THEN 
PRINT "Illegal input...try again" 
RETRY 
ELSE PRINT "In outer_handler" 
PRINT "Reverting to default handling now" 
EXIT HANDLER 
END IF 
END HANDLER 


HANDLER inner_handler 
{Trap overflow/decimal error 
IF ERR = 181 
THEN CONTINUE 
ELSE PRINT "Inside inner_handler" 
PRINT "Reverting to outer handler now" 
EXIT HANDLER 
END IF 
END HANDLER 
END PROGRAM 


Output 


Enter divisor? 0 

Enter dividend? 53 

Inside inner_handler 

Reverting to outer handler now 
Inside outer_handler 

Reverting to default handling now 


%BAS-F-DIVBY_ZER, Division by 0 

-BAS-USEPC_PSL, at user PC=001C18B3, PSL=03COO0A4 
-SYSTEM-F-FLTDIV_F, arithmetic fault, floating divide by zero at 
PC=001C18B3, PSL=O03CO0O0A4 

-BAS-I-FROLINMOD, in module ERROR_7 


For more information about exiting program units while an error is 
pending, see Section 17.2.6. 
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17.2.4 Selecting the Severity of Errors to Handle 


The OPTION HANDLE statement lets you specify the severity level 

of errors that are to be handled by an error handler in addition to the 
BASIC errors that can normally be handled or trapped. You can specify 
any one of the following error severity levels: BASIC, SEVERE, ERROR, 
WARNING, or INFORMATIONAL. 


OPTION HANDLE = BASIC is the default, which is in effect if you do not 
specify an alternative in the OPTION HANDLE statement. Only trappable 
VAX BASIC errors transfer control to the current error handler when this 
option is in effect. Refer to Appendix B to determine which BASIC errors 
are not trappable. 


When you specify an error severity level other than BASIC in the OPTION 
HANDLE statement, the following errors will transfer control to the error 
handler: 


e All trappable BASIC errors of this or lesser severity 
e All non-BASIC errors of this or lesser severity 
e BASIC errors of this or lesser severity that are not normally trappable 


For example, if you specify OPTION HANDLE = ERROR, you can handle 
all BASIC and non-BASIC errors of ERROR severity (both trappable and 
non-trappable), and all WARNING and INFORMATIONAL errors, but no 
SEVERE errors. 


17.2.5 Identifying Errors 


VAX BASIC provides several built-in functions that return information 
about an error. You can use these functions inside your error handlers to 
determine details about the error and conditionally handle these errors. 
These functions include 


e ERR 
e ERL 
e ERN$ 
e ERT$ 


¢ VMSSTATUS 
e RMSSTATUS 
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Note that if an error occurs in your program that is not a VAX BASIC error 
or does not map onto a VAX BASIC error, it is signaled as NOTBASIC 
(“Not a BASIC error”) (ERR = 194). In this case, you can use the built-in 
function VMSSTATUS to determine what caused the error. VMSSTATUS 
is discussed in Section 17.2.5.5. 


17.2.5.1 Determining the Error Number (ERR) 


You use the ERR function to return the number of the last error that 
occurred. Appendix B in this manual lists the number of each VAX BASIC 
run-time error. For instance, ERR 153 is "RECALREXI, Record already 
exists". The following example shows a handler that traps this error: 


Example 


OPTION HANDLE = ERROR 
WHEN ERROR USE find_error 


END WHEN 


HANDLER find_error 
SELECT ERR 
!Record already exists 
CASE = 153 
PRINT "Choose new record" 
CONTINUE 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END HANDLER 


The results of ERR remain undefined until an error occurs. Although ERR 
remains defined as the number of the last error after control leaves the 
error handler, it is poor programming practice to refer to this variable 
outside the scope of an error handler. 
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17.2.5.2 Determining the Error Line Number (ERL) 


After your program generates an error, the ERL function returns the 
BASIC line number of the signaled error. This function is valid only in 
line-numbered programs. The ERL function, like ERR, lets you set up 
branching to one of several paths in the code. 


The following handler continues execution at different points in the 
program, depending on the value of ERL. 


Example 
10 DECLARE INTEGER CONSTANT TRUE = -1 
20 WHEN ERROR USE err_handler 


900 END WHEN 
1000 HANDLER err_handler 
SELECT TRUE 
CASE (ERR = 11) AND (ERL = 790) 
!Is error end of file at line 7907 
PRINT "Completed" 
CONTINUE 


CASE (ERR = 149) AND (ERL = 80) 
!Is error not at end of file on line 80? 
PRINT "CHECK ACCESS MODE" 
CONTINUE 
CASE ELSE 
!Let VAX BASIC handle any other errors 
EXIT HANDLER 
1500 END SELECT 
2000 END HANDLER 
32000 CLOSE #5 
32767 END 


The results of ERL are undefined until an error occurs, or if the error 
occurs in a subprogram not written in VAX BASIC. Although ERL remains 
defined as the line number of the last error even after control leaves the 
error handler, it is poor programming practice to refer to this variable 
outside the scope of an error handler. 


If you reference ERL in a compilation unit with line numbers, code and 
data are included in your program to allow VAX BASIC to determine 
ERL when an exception occurs. If you do not need to reference ERL, 
you can save program size and reduce execution time by compiling 
your program with the /NOLINE qualifier. Note that if your program 
references ERL and you compile the program with the /NOLINE switch, 
VAX BASIC signals the message “ERL overrides /NOLINE” and the 
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program is compiled with the /LINE qualifier. Even if you do not use 
any line numbers, you can reduce execution time by compiling with the 
/NOLINE qualifier. 


If an error occurs in a subprogram containing line numbers, VAX BASIC 
sets the ERL variable to the subprogram line number where the error was 
detected. If the subprogram also executes an EXIT HANDLER statement, 
control passes back to the outer procedure’s handler. The error is assumed 
to occur on the statement where the call or invocation occurs. 


17.2.5.3. Determining Where the Error Occurred (ERN$) 


You use the ERN$ function to return the name of the program unit in 
which the error was detected. ERN$ returns the name of a main program, 
SUB, FUNCTION, or PICTURE subprogram, or DEF function. If the 
PROGRAM statement is used with a user-supplied identifier, the ERN$ 
value is the specified identifier for the main program. The results of ERN$ 
are undefined until the program generates an error. 


In the following example, control passes to the main program for error 
handling if the error occurs in the module SUBARC. 


Example 


HANDLER locat_ern 
IF ERN$ = "SUBARC" 
THEN PRINT "ERROR IS ";ERR 
PRINT "RETURNING TO MAIN PROGRAM FOR ERROR HANDLING" 
EXIT HANDLER 
ELSE PRINT "PROGRAM MODULE GENERATING ERROR IS ";ERN$ 
END IF 
END HANDLER 


Note that ERN$ is invalid when an error occurs in a subprogram compiled 
with the /NOSETUP qualifier. 


17.2.5.4 Determining the Error Message Text (ERT$) 


You use the ERT$ function to access the message text associated with 

a specified error number. Use of the ERT$ function is not limited to 

the scope of the error handler; you can access ERT$ at any time. The 
following detached handler tests whether the error occurred in a DEF 
module named TSLFE, and if so, prints the text of the signaled error and 
resumes execution. 
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Example 


HANDLER catch_it 
IF ERN$ = "TSLFE" 
THEN PRINT ERT$(ERR) 
CONTINUE 
ELSE EXIT HANDLER 
END IF 
END HANDLER 


17.2.5.5 Determining VAX/VMS Error Information 


VAX BASIC provides a built-in function, VMSSTATUS, that returns the 
originally signaled error before it is translated to a BASIC error. For 
instance, for the BASIC error “End of file on device” (ERR = 11), the 
VMSSTATUS function returns "RMS$_EOF” (RMS end of file). This 
function is useful when the error is NOTBASIC (ERR = 194). 


When there is no error pending, VMSSTATUS is undefined. The value 
returned by this function is the actual signaled error value. If non-BASIC 
errors are being handled, the VMSSTATUS function may be the only way 
to find out which error caused the exception. 


The following example shows a program that performs file I/O. The first 
WHEN ERROR block traps any errors that occur while the program is 
opening the file or requesting user input. The detached handler for this 
block checks the value of VMSSTATUS to determine the exception that 
occurred. The inner error handler handles two special errors, BAS$K_— 
RECNOTFOU and BAS$K_RECBUCLOC, separately. If the error signaled 
does not correspond to one of these, the inner error handler passes control 
to the outer handler with the EXIT HANDLER statement. The outer 
handler sets the program status to VMSSTATUS. When the program exits, 
the operating system displays any status that is of warning severity or 
greater. 


Example 


PROGRAM Tester 


OPTION HANDLE = ERROR 
EXTERNAL LONG CONSTANT BAS$K_RECNOTFOU, BAS$K_RECBUCLOC 
DECLARE LONG Final_status 


MAP (Rec_buffer) & 
STRING Rec_key = 65, & 
STRING Rest_of_record = 20 


Final_status = 1 
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WHEN ERROR USE Global_handler 
OPEN "My_database" FOR INPUT AS FILE #1 
, INDEXED FIXED 
, ACCESS READ 
,MAP Rec_buffer 
PRIMARY Rec_key 


& & RP & 


Get_key: 
INPUT "Record to retrieve"; Rec_key 


WHEN ERROR IN 
GET #1%, KEY #0 EQ Rec_key 
PRINT Rest_of_record 
USE 
SELECT ERR 
CASE = BAS$K_RECNOTFOU 
PRINT “Record not found" 
CONTINUE Get_key 


CASE = BAS$K_RECBUCLOC 
SLEEP 2% 
RETRY 
CASE ELSE 
EXIT HANDLER 
END SELECT 
END WHEN 


END WHEN 


HANDLER Global_handler 
Final_status = VMSSTATUS 
END HANDLER 


END PROGRAM Final_status 


17.2.5.6 Determining RMS Error Information 


The RMSSTATUS function lets you determine which RMS error caused 

a resulting VAX BASIC error. You must specify an open channel as the 
first parameter to RMSSTATUS. If this channel is not open, the error 
"I/O channel not open” (ERR = 9) is signaled. The second parameter to 
the function lets you specify either STATUS or VALUE; this parameter 

is optional. If you do not specify the second parameter, RMSSTATUS 
returns the STATUS value by default. STATUS represents the RMS "STS" 
field and VALUE corresponds to the RMS "STV" field. 


The following example shows an error handler that prints both the status 
and the value of any RMS error. 
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Example 


WHEN ERROR IN 
OPEN "file.txt" FOR OUTPUT AS FILE 1% 
PRINT #1%, TIME$(0%) 


USE 
!'Error 12 is fatal system I/0 failure 
IF ERR = 12 
THEN 
PRINT "An unexpected RMS error has occurred:" 
PRINT "Status = "; RMSSTATUS(1%) 
PRINT "Value = "; RMSSTATUS(1%, VALUE) 
EXIT HANDLER 
END IF 
END WHEN 


CLOSE #1% 
GOTO done 


done: 
END 


If you want to find an RMS status without knowing which particular 
channel to check, you can use VMSSTATUS to get the STATUS value 
(STS) if an error has occurred. 


17.2.6 CTRL/C Trapping 


Error handling procedures are commonly used to trap user CTRL/C 
responses. With CTRL/C trapping enabled, control is transferred to an 
error handler if a user presses CTRL/C during program execution. You 
enable CTRL/C trapping in your program by invoking the built-in CTRLC 
function. For example: 


Y% = CTRLC 


After you invoke the CTRLC function, a CTRL/C entered at the terminal 
transfers control to the error handler. Once the CTRL/C is trapped, 
you can include routines to interact with the program, as shown in the 
following example. 
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Example 


WHEN ERROR IN 
Y% = CTRLC 
OPEN 'FIL_DAT' FOR INPUT AS FILE #1% 
INPUT "HOW MANY RECORDS"; Rec_read%, 
FOR I% = 1% TO Rec_read% 
GET #1% 
PRINT Name$, Address$, Emp_code%, 
PRINT 


NEXT I% 


USE 
!Trap “C 
IF (ERR = 28%) 
THEN PRINT "CURRENT RECORD IS "; I% 
ELSE EXIT HANDLER 
END IF 
CONTINUE Clean_up 
END WHEN 


Clean_up: 

CLOSE #1% 

PRINT "END OF PROCESSING" 
END 


Output 

SMITH, DEXTER 231 COLUMBUS ST 09341 

TRAVIS, JOHN PO BOX 80 64119 

“Cc 

THE CURRENT RECORD IS 3 

END PROCESSING 

Note that the error condition is still pending until the error handler 
executes the CONTINUE statement. Therefore, if you press CTRL/C a 


second time while the error handler is executing, control returns to the 
VAX BASIC error handler, which terminates the program. 


To disable CTRL/C trapping, use the RCTRLC function. The RCTRLC 
function disables only CTRL/C trapping, not the CTRL/C interrupts 
themselves. Alternatively, to prevent both CTRL/C and CTRL/Y from 
interrupting a program, use the DCL command SET NO CONTROL, 
or the RTL routine LIBSDISESTABLISH. See the VAX BASIC Reference 
Manual for more details about the CTRLC and RCTRLC functions. 


Handling Run-Time Errors 17-19 


17.2.7 Handling Errors in Multiple-Unit Programs 


You can use WHEN ERROR constructs anywhere in your main program 
or program modules. Procedure and function invocations, such as invo- 
cations of DEF and DEF* functions and SUB, FUNCTION, and PICTURE 
subroutines, as well as non-BASIC programs, are valid within protected re- 
gions. GOTO and GOSUB statements are valid within handlers provided 
that the target is within the handler, an outer handler, or an unprotected 
region. Note, however, that a detached handler cannot appear within DEF 
or DEF* functions without the associated protected region. 


When an error occurs within nested handlers, VAX BASIC maintains 

the same priorities for handler use; control always passes to the han- 
dler associated with the innermost protected region in which the error 
occurred. When an exception occurs, all handlers for any outer WHEN 
ERROR blocks are processed before the program reverts to default error 
handling. Outer handlers are invoked when an inner handler executes an 
EXIT HANDLER statement. When there are no more outer handlers, and 
the outermost handler executes an EXIT HANDLER statement, program 
control reverts to the handler associated with the calling routine. 


Example 


SUB LIST(A$) 
WHEN ERROR USE sub_handler 


OPEN A$ FOR INPUT AS FILE #12% 


Get_data: 
LINPUT #12%, B$ 
PRINT B$ 
GOTO Get_data 
END WHEN 


HANDLER sub_handler 
!Trap end of file 
IF ERR <> 11% 
THEN EXIT HANDLER 
END IF 
END HANDLER 
CLose_up: 
CLOSE #12% 
END SUB 


You can call a subprogram while an error is pending; however, if you do, 
the subprogram cannot re-signal an error back to the calling program. If 
the subprogram tries to re-signal an error, VAX BASIC signals “Improper 
error handling” and program execution terminates. 
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The following rules apply to error handling in function definitions: 


e DEF and DEF* function definitions cannot appear within a protected 


region. However, protected regions can be contained within the 


function definitions. 


¢ To trap errors while a DEF function is active, include protected regions 
inside the DEF function. If you do this, the associated handler remains 
in effect until your program leaves the protected region, or the DEF 


function. 


Example 
WHEN ERROR IN 


Invoke_def: 


AY = FNIN_PUT% ("PROMPT") 
USE 


PRINT "ERROR"; ERT$(ERR%) ; 
IF ERN$ = "FNIN_PUT" 
THEN PRINT "IN FUNCTION" 
CONTINUE 
ELSE PRINT "IN MAIN" 
CONTINUE Invoke_def 
END IF 
END WHEN 


Main_code: 
DEF FNIN_PUT%(P$) 
WHEN ERROR IN 
PRINT P$ 
INPUT LINE_IN$ 
FNIN_PUT% = INTEGER(LINE_IN$) 


USE 
IF ERR = 50 
THEN RETRY 
ELSE EXIT HANDLER 
END IF 
END WHEN 
END DEF 
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NOTE 


A pending error is passed to VAX BASIC default error handling 
procedures under the following conditions: 


e If you use a GOSUB statement and the invoked procedure 
is not lexically contained within any protected region 


e If you invoke a DEF* function and the DEF* function is not 
lexically contained within any protected region 


Under these circumstances, a pending error is passed to the 
VAX BASIC default error handling even when the invoking 
statement is contained within a protected region. A handler 
associated with the invoking statement will not be used. 


17.2.8 Forcing Errors 


The CAUSE ERROR statement allows a program to artificially generate an 
error when the program would not otherwise do so. You can force any 
VAX BASIC run-time error. You must specify the number of the error the 
compiler should force; the error numbers are listed in Appendix B of this 
manual. The following statement forces an end-of-file error (ERR = 11) to 
occur. 


CAUSE ERROR 11% 


You can use this feature to debug an error handler during program 
development, as shown in the following example: 


Example 
WHEN ERROR IN 


CAUSE ERROR 11% 
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USE 
SELECT ERR 
CASE = 11% 
PRINT "Trapped an end of file on device" 
CONTINUE 
CASE ELSE 
EXIT HANDLER 
END WHEN 


17.3 Using the ON ERROR Statements 


VAX BASIC supports ON ERROR statements as an alternative to WHEN 
blocks primarily for compatibility with existing programs. WHEN ERROR 
blocks are similar to declarative statements in that they do not depend 
on run-time flow of control. The ON ERROR statements, however, affect 
error handling only if the statements execute at run time. For example, if 
a GOTO statement precedes an ON ERROR statement, the ON ERROR 
statement will not have any effect because it does not execute. 


WHEN ERROR blocks let you handle errors that occur in a specific range 
of statements. ON ERROR statements let you specify a general error 
handler that is in effect until you specify another ON ERROR statement or 
until you pass control to the VAX BASIC error handler. 


NOTE 


For all current program development, DIGITAL recommends 
that you use WHEN ERROR constructs for user-written error 
handlers. Mixing WHEN ERROR constructs and ON ERROR 
statements within the same program is not recommended. The 
ON ERROR statements are supported for compatibility with 
other versions of DIGITAL BASICs. It is important to note that 
all of these statements are illegal within a protected region, or 
an attached or detached handler. 


The ON ERROR statements are fully documented in the VAX BASIC 
Reference Manual. This section merely illustrates the main features of the 
ON ERROR statements. 


The ON ERROR statements can be used to transfer control to a labeled 
block of error handling code. If you have executed an ON ERROR 
statement and an error occurs, the ON ERROR statement immediately 
transfers control to the label or line number that starts the error handling 
code. Otherwise, the ON ERROR statement specifies the branch to be 
taken in the event of an error. 
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There are three forms of the ON ERROR statement: 
e ON ERROR GOTO 0 


The ON ERROR GOTO 0 statement reverts control to VAX BASIC 
default error handling in one of two ways: 


— If an error is pending, execution of the ON ERROR GOTO 0 state- 
ment returns control to the VAX BASIC error handler immediately. 


— If no error is pending, an ON ERROR GOTO 0 statement disables 
your current error handler. The VAX BASIC error handler handles 
all subsequent errors until another ON ERROR statement is 
executed, unless an error occurs in a WHEN ERROR protected 
region. 


e ON ERROR GO TO target 


The ON ERROR GOTO target statement reverts control to the target 
when subsequent errors occur that are not handled by WHEN block 
handlers. 


e ON ERROR GO BACK 


The ON ERROR GO BACK statement transfers control to the calling 

. program’s error handler if an error occurs in the subprogram or DEF 
function. If you use ON ERROR GO BACK in a PROGRAM unit 
(outside of a DEF function) and no other outer protected region exists, 
it is equivalent to ON ERROR GOTO 0 and VAX BASIC default error 
handling is in effect. With ON ERROR GO BACK, if an error occurs in 
the execution of a function or subprogram, the error is passed to either 
the error handler of the surrounding program module (in the case of 
a DEF function definition) or the error handler of the calling program 
(in the case of a separately compiled subprogram). 


An error handler in the DEF function does not permanently override 
an error handler in the main program. VAX BASIC saves the error 
handler in the main program when you transfer into a DEF, and 
restores it when you return. 


Traditionally, the ON ERROR GOTO statement is placed before any other 
executable statements. The following example clears end-of-file errors 
and passes all other errors back to the VAX BASIC default error handling 
procedures. 
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Example 


5 ON ERROR GOTO Error_handler 


Error_handler: 
!Trap end of file on device 


IF ERR = i1 
THEN 
RESUME 1000 
ELSE 
ON ERROR GO BACK 
END IF 


The ON ERROR GOTO statement remains in effect after your program 
successfully handles an error. When the system signals another error, 
control once again transfers to the specified error handler. 


Every ON ERROR error handler must end with one of the following 
statements: 


e RESUME [target] 
e ON ERROR GOTO 0 
e ON ERROR GO BACK 


If none of these statements is present, the VAX BASIC error handler aborts 
your program with the fatal error “Error trap needs RESUME” as soon as 
an END, END SUB, END DEF, END FUNCTION, END PROGRAM, or 
END PICTURE statement is encountered. The RESUME statement, like 
the RETRY and CONTINUE statements, clears the error condition. 


You can resume execution at any line number or label that is in the same 
module as the RESUME statement, unless that line or target is inside 

a DEF function, a WHEN ERROR protected region, or a handler. In 
general, RESUME without a target transfers control to the beginning of 
the program block where the error occurred. 


e If you resume execution at a multi-statement line, execution begins at 
the first statement after the line number or label—not necessarily at 
the statement that generated the error. 


e If an entire loop block is associated with a single line number or label 
and an error occurs within the loop, RESUME with no target transfers 
control to the statement immediately after the FOR, WHILE, or UNTIL 
statement, not to the line number or label. 


For more details on the RESUME statement, see the VAX BASIC Reference 
Manual. 
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DIGITAL does not recommend using both ON ERROR statements and 
WHEN ERROR constructs in the same program. However, when this is 
the case, the order of handler priorities is as follows: 


1. Control passes to the handler associated with the innermost WHEN 
ERROR block. 


2. If protected regions are nested, the pending error is handled by the 
handler associated with the next outer WHEN ERROR block. 


3. When no outer protected regions can handle the error, and if an ON 
ERROR statement is in effect, control transfers to the target of the next 
outer ON ERROR statement (if one is present). 


4. If no outer handler is available or can handle the error, the error is 
passed to VAX BASIC default error handling. Default error handling 
is equivalent to ON ERROR GOTO 0. 


For information on specific run-time errors, refer to Appendix B in this 
manual. 
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Chapter 18 


Compiler Directives 


Compiler directives are instructions that tell VAX BASIC to perform certain 
operations as it translates a source program. This chapter describes how 
to control program compilation using compiler directives. 


18.1 Introduction 


With compiler directives, you can do the following: 


Place program titles and subtitles in the header that appears on each 
page of the listing file 


Place a program version identification string in both the listing file and 
the object module 


Start or stop the inclusion of listing information for selected parts of a 
program 


Start or stop the inclusion of cross-reference information for selected 
parts of a program 


Include VAX BASIC code from another source file or a text library 
Include CDD record definitions in a VAX BASIC program 

Record dependency relationships in the CDD 

Display a message at compile time 

Conditionally compile parts of a program 

Terminate compilation 


When using compiler directives follow these rules: 


Directives must begin with a percent sign. 
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18.2 Controlli 


Directives can be preceded by an optional line number. 


Directives must be the only text on the line (except for %IF-%THEN- 
%ELSE-%END %IF). 


Directives cannot appear within a quoted string. 


Directives cannot follow an END, END SUB, or END FUNCTION 
statement. 


ng the Compilation Listing 


Listing directives let you control the content and appearance of the 
compilation listing. There are eight compiler listing directives: 


The 
The 


%TITLE places a title string on the first line of the listing header. 


%SBTTL places a subtitle string on the second line of the listing 
header. 


%IDENT places an identification string on the second line of the 
listing header and within the object module. 

%PAGE causes VAX BASIC to skip to top-of-form in the output 
listing. 

%NOLIST causes VAX BASIC to stop accumulating information for 
the output listing. 

%LIST causes VAX BASIC to resume accumulating information for the 
output listing. 

%NOCROSS causes VAX BASIC to stop accumulating cross-reference 
information for the output listing. 


% CROSS causes VAX BASIC to resume accumulating cross-reference 
information for the output listing. 


se directives are described in the following sections. 


listing control directives have no effect if no source program listing is 


being produced. Similarly, the %CROSS and %NOCROSS directives have 
no effect if no cross-reference listing is being produced. However, the 
%IDENT directive places the specified text in the object module whether 
or not a listing is produced. For more information on how these directives 
affect your source code, see Chapter 4. 
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18.2.1 The %TITLE and %SBTTL Directives 


The %TITLE directive lets you specify a line of text that appears on the 
first line of every page in the compilation listing. This text line is a quoted 
string of up to 45 characters and normally contains the source program 
title and other information. 


If the %TITLE directive is the first source text in a module, then the quoted 
string appears in the first line of every page of the compilation listing. 
‘Otherwise, the quoted string appears in the first line of every subsequent 
page in the compilation listing. That is, if VAX BASIC encounters a 
%TITLE directive after it has begun creating a page in the output listing, 
the title information will not appear on that page. Rather, it appears on all 
of the following pages until it encounters another %TITLE directive. 


The quoted string appears in character positions 33 to 81 in the first line 
of the listing header. % TITLE must appear on its own line. For example: 


“TITLE "File OPEN Subprogram -- Author Hugh Ristics" 
SUB FILSUB (STRING F_NAME) 


The %SBTTL directive lets you specify a line of text that appears on the 
second line of every page in the compilation listing (beneath the title). If 
VAX BASIC encounters a %SBTTL directive after it has begun creating a 
page in the output listing, the subtitle information will not appear on that 
page. Rather, it appears on all following pages until it encounters another 
%SBTTL or %TITLE directive. If you want the subtitle to appear on the 
first page, the %SBTTL directive must appear directly after the %TITLE 
directive. 


Any number of %SBTTL directives can appear in a source file; thus, 
you can use subtitle text to identify parts of the source program. As 

in %TITLE, the text you use in %SBTTL must be a quoted string not 
exceeding 45 characters. The quoted string appears in the second line of 
the listing header, in character positions 33 to 81. Note, however, that 
subtitle information only appears on listing pages that contain the actual 
source code. 


The following example shows the use of both %TITLE and %SBTTL 
directives. The first line of the listing’s first page contains “Payroll 
Program” and the second line contains “Constant Declarations.” When 
VAX BASIC encounters the %SBTTL directive, the second line on each 
subsequent page becomes “Subroutines”. When VAX BASIC encounters 
the %SBTTL directive, the second line on each subsequent page becomes 
“Error Handler”. 
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Example 


“TITLE "Payroll Program" 
“SBITL "Constant Declarations" 


“%4SBITL "Subroutines" 


YSBTTL "Error Handler" 


You can use multiple %TITLE directives in a single source file; however, 
whenever VAX BASIC encounters a %TITLE directive, the %SBTTL 
information is set to the null string. Therefore, if you want to display 
subtitle information, each new %TITLE directive should be accompanied 
by a new %SBTTL directive. 


18.2.2 The %IDENT Directive 


The %IDENT directive identifies the version of a program module. The 
identification text must be a quoted string of up to 31 characters. The 
information contained within the identification text appears in the listing 
file and the object module. Thus, the map file created by the VAX/VMS 
Linker also contains this information. 


The identification text appears in the first 31 character positions of the 
second line on each subsequent listing page. For instance, in the following 
example, the %IDENT information appears as the first entry on the second 
line of the listing. The information is also included in the object module 
if the compilation produces one. If the linker generates a map listing, this 
information also appears there. 


Example 


“ZIDENT "V5.3" 
SUB PAY 


If your source module contains multiple %IDENT directives, VAX BASIC 
signals a warning and uses the version specified in the first %IDENT 
directive. 
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18.2.3 The %PAGE Directive 


The %PAGE directive causes VAX BASIC to begin a new page in the 
listing file. In the following example, the %PAGE directives cause VAX 
BASIC to skip to a new page in the listing file just before each new 
subtitle. Note that, in order to have title and subtitle information appear 
in the heading of each page, you cannot place a line number between the 
%PAGE, %TITLE, and %SBTTL directives. 


Example 


“TITLE "Payroll Program" 
%SBTTL “Constant Declarations" 


Y,PAGE 
4SBTTL "Subroutines" 


PAGE 
4SBITL "Error Handler" 


18.2.4 The %LIST and %NOLIST Directives 


%LIST and %NOLIST are complementary directives. The %LIST directive 
causes VAX BASIC to resume adding information to the listing file, while 
the %NOLIST directive causes VAX BASIC to stop adding information 

to the listing file. Therefore, you can control which parts of the source 
program are to be listed. 


In the following example, as soon as VAX BASIC encounters the %LIST 
directive, it resumes adding new information to the listing file. 
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Example 


“TITLE "Payroll Program" 
YSBTTL "Constant Declarations" 


4NOLIST 
“LIST 


%PAGE 
YSBTTL "Subroutines" 


Y%PAGE 
YSBTTL "Error Handler" 


If you have not requested the creation of a compilation listing, the %LIST 
and %NOLIST directives have no effect. 


If a program line contains a syntax error, VAX BASIC overrides the 
%NOLIST directive for that line and produces the normal error diagnostics 
in the listing file. 


18.2.5 The %CROSS and “%NOCROSS Directives 


The %CROSS and %NOCROSS directives are complementary. The 

% CROSS directive causes VAX BASIC to resume adding cross-reference 
information, while the %NOCROSS directive causes VAX BASIC to 
stop adding cross-reference information to the listing file. Therefore, 
you can specify that only certain parts of the source program are to be 
cross-referenced. 


In the following example, as soon as VAX BASIC encounters the %CROSS 
directive, it resumes adding new cross-reference information to the listing 
file. 
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Example 


“%TITLE "Payroll Program" 
¥YSBTTL "Constant Declarations" 


“%NOCROSS 
4CROSS 


7,PAGE 
YSBTTL "Subroutines" 


7PAGE 
4SBITL "Error Handler" 


If you have not requested the creation of a cross-reference listing, the 
%CROSS and %NOCROSS directives have no effect. 


18.3 Accessing External Source Files 


The %INCLUDE directive lets you access VAX BASIC source text from 
a file into the source program. The %INCLUDE directive also lets you 
access record definitions in the VAX Common Data Dictionary (CDD) 
as well as access source text from a text library. The line on which a 
%INCLUDE directive resides can be continued, but cannot contain any 
other directives or statements. 


If you are including a source text file, you must supply a file specification. 
If you do not provide a file type, VAX BASIC uses the default type BAS. 
For example: 


“INCLUDE "KEN.BAS" 


If you are including a CDD definition, you must supply a valid VAX CDD 
path specification to extract a RECORD definition from the CDD. For 
example: 


%INCLUDE %FROM 4.CDD "CDD$TOP.EMPLOYEE" 
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See Chapter 23, the VAX BASIC Reference Manual and the VAX Common 
Data Dictionary Utilities Reference Manual for more information. 


If you are including source text from a text library, you must supply the 
name of the text module you wish to include as well as the name of the 
library where the module resides. If you do not specify a library name, 
VAX BASIC uses the default library, BASIC$LIBRARY. Moreover, if you 
do not specify a directory name or file type, VAX BASIC uses the default 
device and the file type TLB. 


In the following example, when VAX BASIC encounters the %INCLUDE 
directive, the compiler searches through the library SYS$LIBRARY:BASIC_. 
LIB.TLB for the specified module DMB_TEST and compiles the text as if it 
were placed in the position of the %INCLUDE directive. 


%INCLUDE "DMB_TEST" %FROM {LIBRARY "SYS$LIBRARY : BASIC_LIB.TLB" 


VAX BASIC supplies the text library BASICSSTARLET located in 
SYS$LIBRARY. This text library contains condition codes and other sym- 
bols defined in the system object and shareable image libraries. Using the 
definitions from BASIC$STARLET allows you to reference condition codes 
and other system-defined symbols as local, rather than global symbols. 


To create your own text libraries using the VAX/VMS Librarian Utility, 
see the VAX/VMS Librarian Reference Manual. 


All file specifications, CDD path specifications, text modules and library 
specifications must be string literals enclosed in quotes. 


The source files accessed with %INCLUDE cannot contain line numbers. 
This requirement means that all statements in the accessed file are asso- 
ciated with the VAX BASIC line containing the %INCLUDE directive if 
line numbers are being used. Therefore, if you are using line numbers, 
a %INCLUDE directive cannot appear before the first line number in 

a source program. A file accessed by %INCLUDE can itself contain a 
%INCLUDE directive. 


When a program is compiled, VAX BASIC inserts the included text at the 
point at which it encounters the %INCLUDE directive. The compilation 
listing identifies any text obtained from an included file by placing a 
mnemonic in the first character position of the line in which the text 
appears. “In” specifies text that was either accessed from a source file or 
from a text library, and “Cn” specifies a record definition that was accessed 
from the CDD. Both the I and the C tell you that the text was accessed 
with the %INCLUDE directive, and n tells you the nesting level of the 
included text. 
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The %INCLUDE directive is useful when you want to share code among 
multiple program modules. To do this, you must first create a file that 
contains the shareable code, then include that file in all the modules that 
require it. Thus, you reduce the chance of a typographical error. 


You can prevent the %INCLUDE file code from appearing in the compila- 
tion listing by using the BASIC command qualifier /SHOW=NOINCLUDE 
or /SHOW=NOCDD_DEFINITIONS. For text files and text library mod- 
ules, use the qualifier /SHOW=NOINCLUDE. For CDD definitions, use 
the qualifier /SHOW=NOCDD_DEFINITIONS. 


18.4 Controlling Compilation 


VAX BASIC lets you control the compilation of a program by creating and 
testing lexical constants. You create and assign values to lexical constants 
with the %LET directive. These constants are always LONG integers. 


You control the compilation by using the %IF-%THEN-%ELSE-%END 
%IF directive to test these lexical constants. Thus, you can conditionally: 
¢ Supply different values for program variables and constants 

e Skip over part of a program 

e Abort a compilation 

e Include VAX BASIC source code from another file 

e¢ Display informational messages during the compilation 


VAX BASIC also supplies the lexical built-in function % VARIANT that can 
be used to conditionally control compilation. 


%IF-%THEN-%ELSE-%END %IF uses lexical expressions to determine 
whether to execute directives in the %THEN clause or the %ELSE clause. 
The following sections describe the use of: 

e Lexical constants and expressions (%LET Directive) 

¢ = =%VARIANT 

¢ %ABORT 

© %PRINT 

e = =6%IF-%THEN-%ELSE-%END %IF 
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18.4.1 The %LET Directive 


The %LET directive creates and assigns values to lexical constants. Lexical 
constants are always LONG integers. These constants control the execu- 
tion of the %IF-%THEN-%ELSE-%END %IF directive. 


All lexical constants must be created with %LET before they can be used 
in a %IF-%THEN-%ELSE-%END %IF, and each lexical constant must be 
created with a separate %LET directive. All lexical constant names must 

also be preceded by a percent sign and cannot end with a dollar sign or 

percent sign. 


A lexical expression can be: 

e A lexical constant 

e An integer literal 

e =A lexical built-in function (% VARIANT) 

e Any combination of these, separated by logical, relational, or arith- 
metic operators 

The %LET directive lets you create constants that control conditional 

compilation. For example: 


“LET %debug_on = 0% 


See Section 18.4.5 for an example of using %LET with %IF-%THEN- 
%ELSE. 


18.4.2 The “VARIANT Directive 


The % VARIANT directive is a built-in lexical function that returns an 
integer. The value of this returned integer is determined by: 


e The SET VARIANT command when a program is compiled in the 
BASIC environment. 


e The /VARIANT qualifier when a program is compiled from the system 
command level or from within the BASIC environment. 


The % VARIANT function returns the variant value set with either of these 
methods. 


The default value for the % VARIANT function is zero. See Section 18.4.5 
for an example of controlling compilation with % VARIANT. 
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18.4.3 The %ABORT Directive 


The %ABORT directive terminates the compilation and displays a message 
you provide. 


The text must be a quoted string literal. This information is displayed to 
SYS$ERROR and in the compilation listing if one is being created. VAX 
BASIC stops the compilation and terminates the listing file as soon as it 
encounters a % ABORT directive, and so VAX BASIC does not perform 
syntax checking on the remainder of the program. See Section 18.4.5 for 
an example of using % ABORT. 


18.4.4 The “PRINT Directive 


The %PRINT directive allows you to insert a message into your source 
code that the VAX BASIC compiler displays at compile time. 


The text must be a quoted string literal. This information is displayed to 
SYS$ERROR and in the compilation listing if one is being created. VAX 
BASIC prints the message specified as soon as it encounters a %PRINT 

directive. See Section 18.4.5 for an example of using %PRINT. 


18.4.5 The “IF-%“THEN-%ELSE-%END “IF Directive 


The %IF-%THEN-%ELSE-%END %IF directive lets you do the following 
things conditionally: 


¢ Compile source text 
e Execute another compiler directive 


This directive differs from all others in that it can appear anywhere in a 
program where a space is allowed, except within a quoted string. 


You must include %END %IF. Otherwise, the rest of the source program 
becomes part of the %THEN or %ELSE clause. You must also include a 
lexical expression and some VAX BASIC source code. 


The truth or falsity of the lexical expression determines whether VAX 
BASIC compiles the source code in the %THEN clause or the %ELSE 
clause. If the lexical expression is true, VAX BASIC neither compiles 
nor checks the syntax of source code in the %ELSE clause. If the lexical 
expression is false, VAX BASIC neither compiles nor checks the syntax of 
source code in the %THEN clause. 
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The following example also uses the % VARIANT directive, which returns 
the value set by the SET VARIANT command or /VARIANT qualifier: 


Example 


%IF (%VARIANT = 2%) 

“THEN DECLARE LONG int_array(100) 
%ELSE DECLARE WORD int_array(100) 
%END %IF 


This directive allows for two possibilities. If you compile this program 
with a /VARIANT=2 qualifier, then VAX BASIC creates an array of 
longword integers. If you compile this program with any other variant 
value, VAX BASIC creates an array of word integers. 


Because %IF can appear within a program line, you can express the same 
directive this way: 


DECLARE %4IF (%VARIANT=2%) %THEN LONG %ELSE WORD %END 4%IF int_array (100) 


A %THEN or %ELSE clause can also contain other compiler directives. 
For example, the following program creates the lexical constant %my_ 
constant and assigns it a value of 8. The %IF directive evaluates the 
conditional expression ((%my_constant + %VARIANT) > = 10%). If this 
expression is true, VAX BASIC executes the %THEN clause, aborting 
the compilation and issuing an error message. If the expression is false, 
VAX BASIC prints the specified message and continues to compile your 
program without aborting the compilation. 


‘Example 


“LET %my_constant = 8% 

“4IF ( (%my_constant + %VARIANT) >= 10% )%THEN 
%ABORT "Cannot compile with VARIANT >= 2" 
ELSE %PRINT "Successful Compilation" 

ZEND %IF 


The compilation listing shows you which clause was actually compiled. 


18-12 Compiler Directives 


Example 


“LET %my_constant = 8%, 

%IF ( (A’my_constant + %VARIANT) >= 10% )%THEN 
ZABORT "Cannot compile with VARIANT >= 2" 
ELSE %PRINT "Successful Compilation" 

%END %IF 


The compilation listing shows you which clause was actually compiled. 


18.5 Record Dependency Relationships in the CDD 


By using the %INCLUDE %FROM %CDD or the %REPORT 

% DEPENDENCY directives in conjunction with the 
/DEPENDENCY_DATA qualifier in the BASIC command, you can record 
dependency relationships in a CDO dictionary between a compiled 
module entity and included records or other referenced dictionary entities. 
This functionality is available only if you have CDD/Plus Version 4.0 or 
later installed on your system. 


See Chapter 24 for detailed information. 
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USING VAX BASIC FEATURES ON VAX/VMS 


Chapter 19 
Data Representation 


This chapter describes how to represent data using VAX BASIC on the 
VAX/VMS operating system. 


19.1 Integer Format 


There are three ways in which integer data can be represented: byte, 
word, and longword. Note that negative integer values are stored in 
two’s complement format. The following sections describe each of these 
formats. 


19.1.1 Byte-Length Integer Format 
Byte-length integers are in the range -127 to 128 and are stored as a single 


byte (8 bits), starting on an arbitrary byte boundary. Bits are labeled from 
the right, 0 through 7. See Figure 19-1. 
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Figure 19-1: Byte-Length Integer Format 
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19.1.2 Word-Length Integer Format 


Word-length integers are in the range ~32768 to 32767 and are stored 
as two contiguous bytes, starting on an arbitrary byte boundary. Bits are 
labeled from the right, 0 through 15. See Figure 19-2. 


Figure 19-2: Word-Length Integer Format 
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19.1.3 Longword Integer Format 


Longword integers are stored as four contiguous bytes, starting on an arbi- 


trary byte boundary. Values are in the range -2147483647 to 2147483647. 
See Figure 19-3. 
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Figure 19-3: Longword Integer Format 
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19.2 Real Number Format 


Real numbers, like integers, can be represented in varying formats. These 

formats include SINGLE floating-point, DOUBLE floating-point, GFLOAT 

floating-point, HFLOAT floating-point, and packed DECIMAL format. The 
following sections describe each of these formats. 


19.2.1 SINGLE Floating-Point Number Format (F_floating) 


F_floating (single-precision) floating-point numbers are stored as four 
contiguous bytes, starting on an arbitrary byte boundary. Bits are labeled 
from the right, 0 through 31. 


The format for single-precision is sign magnitude, with bit 15 the sign 
bit, bits 14 to 7 an excess-128 binary exponent, and bits 6 through 0 
and 31 through 16 a normalized 24-bit fraction with the redundant 
most significant fraction bit not represented. See Figure 19-4. The 8-bit 
exponent field encodes the values between 0 and 255, inclusive. 


An exponent value of 0 together with a sign bit of 0 indicates that the 
F_floating number has a value of 0. Exponent values between 1 and 255 
indicate true binary exponents of -127 through 127. An exponent value 
of 0, together with a sign bit of 1, is taken as reserved. (Floating-point 
instructions processing a reserved operand take a reserved operand fault.) 
The magnitude of an F_floating number is in the approximate range 

.29 * 10~ 38 through * 10°°. The precision of an F_floating number is 
approximately one part in 27? (approximately 7 decimal digits). 


Data Representation 19-3 


Figure 19-4: Single-Precision Real Number Format 
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19.2.2 DOUBLE Floating-Point Number Format (D_floating) 


Double-precision real number format consists of eight contiguous bytes, 
starting on an arbitrary byte boundary. Bits are labeled from the right, 0 
through 63. See Figure 19-5. The form of a D_floating number is iden- 
tical to the F_floating form, except for an additional 32 low-significance 
fraction bits. Within the fraction, bits increase in significance from 48 

to 63, 32 through 47, 16 through 31, and 0 through 6. The exponent 
conventions and approximate range of values is the same for both D_ 
floating and F_floating numbers. The precision of a D_floating number is 
approximately one part in 2°° (approximately 16 decimal digits). 
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Figure 19-5: Double-Precision Real Number Format 
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19.2.3 GFLOAT Floating-Point Number Format (G—floating) 


The G_floating floating-point number format is eight contiguous bytes, 
starting on an arbitrary byte boundary. Bits are labeled from the right, 0 
through 63. The form of a G_floating number is sign magnitude with bit 
15 the sign bit, bits 14 through 4 an excess-1024 binary exponent, and 
bits 3 through 0 and 63 through 16 a normalized 53-bit fraction with the 
redundant most significant fraction bit not represented. 


Within the fraction, bits of increasing significance go 48 through 63, 32 
through 47, 16 through 31, and 0 through 3. The 11-bit exponent field 
encodes the values 0 through 2047. 


An exponent value of 0 together with a sign bit of 0 indicates that the 
G_floating number’s value is 0. Exponent values between 1 and 2047 
indicate true binary exponents between -1023 and 1023. The value of 

a G_floating number is in the approximate range .56 * 10 —°°8 to 

.9 * 10°°8; the precision is approximately one part in 2°? (approximately 
15 decimal digits). Note that both double and G_floating formats require 
8 bytes. G_floating format provides a greater range, but less precision 
than double. 
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19.2.4 HFLOAT Floating-Point Number Format (H _floating) 


An H_floating floating-point number is 16 contiguous bytes, starting on 
an arbitrary byte boundary. H_floating format combines a large range 
with extensive precision, but requires twice the amount of storage of 
double and G_floating. The bits are labeled from the right 0 through 127. 
The form of an H_floating number is sign magnitude with bit 15 the sign 
bit, bits 14 to 0 an excess -16384 binary exponent, and bits 127 to 16a 
normalized 113-bit fraction with the redundant most significant fraction 
bit not represented. 


Within the fraction, bits of increasing significance go 112 through 127, 96 
through 111, 80 through 95, 64 through 79, 48 through 63, 32 through 
47, and 16 through 31. The 15-bit exponent field encodes the values 0 
through 32767. 


An exponent value of 0 together with a sign bit of 0 indicates the 
H_floating number has a value of 0. Exponent values between 1 and 
32767 indicate true binary exponents between —16383 and 16383. The 
value of an H_floating number is in the approximate range .84 * 1049? 
through .59 * 104997. The precision of an H_floating number is approxi- 
mately one part in 2'!? (approximately 33 decimal digits). 


19.3 Packed Decimal Number Format 


The DECIMAL data type is useful for storing numbers with a fixed decimal 
point. DECIMAL numbers are stored as a precise representation of the 
value stored within the constraints of the specified number of fractional 
digits. A packed decimal string is a contiguous sequence of bytes in 
memory. The address A and length L are sufficient to specify a packed 
decimal string, but note that L is the number of digits, not bytes, in the 

_ String. Every byte of a packed decimal string is divided into two 4-bit 
fields (nibbles), each of which must contain decimal digits, except the low 
nibble of the last byte, which must contain a sign. The representation for 
the digits and sign is as follows: 
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Digit or Sign Decimal Hexadecimal 


0 0 0 

1 1 1 

2 2 2 

3 3 3 

4 4 4 

2, 5 5 

6 6 6 

Z 7 7 

8 8 8 

9 9 9 

+ 10,12,14 or 15 A,CE or F 
- 11 or 13 Bor D 


Despite the options, the preferred sign representation is 12 for positive 
and 13 for negative. The length L is the number of digits in the packed 
decimal string (not counting the sign) and must be in the range 1 through 
31. If the number of digits is odd, the digits and the sign fit into 

((L/2) + 1) bytes; when the number of digits is even, an extra “0” digit 
must appear in the high nibble (bits 7 to 4) of the first byte. 


The address A of the string specifies the byte of the string containing the 
most significant digit in its high nibble. Digits of decreasing significance 
are assigned to increasing byte addresses and from high nibble to low 
nibble within a byte. 


Note that the decimal point is specified by the descriptor for the packed 
decimal string. See Section 19.6. 


19.4 String and Array Descriptor Format 


A descriptor is a VAX/VMS data structure that describes the parameter 
being passed. The following sections describe the formats for both string 
and array descriptors. 
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19.4.1 Fixed-Length String Descriptor Format 


A fixed-length string descriptor consists of two longwords. The first word 
of the first longword contains a value equal to the string’s length. The 
third byte contains a 14 (OE hexadecimal; the VAX/VMS code describing 
an ASCII character string). The fourth byte contains a 1. The second 
longword is a pointer containing the address of the string’s first byte. 
See Figure 19-6. For more information, see the Introduction to VAX/VMS 
System Routines for the VAX Procedure Calling and Condition Handling 
Standard. 


Figure 19-6: Fixed-Length String Descriptor Format 


CT = [wen 
POINTER 


ZK-5178-86 










19.4.2 Dynamic String Descriptor Format 


A dynamic string descriptor consists of two longwords. The first word 
of the first longword contains a value equal to the string’s length. The 
third byte contains a 14 (OE hexadecimal; the VAX/VMS code describing 
an ASCII character string). The fourth byte contains a 2. The second 
longword is a pointer containing the address of the string’s first character. 
See Figure 19-7. 
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Figure 19-7: Dynamic String Descriptor Format 





POINTER 


Z2K-5179-86 


19.5 Array Descriptors 


VAX BASIC creates class A array descriptors (DSC$K_CLASS_A) for 

all arrays except virtual arrays. Virtual array descriptors differ in format 
and can be manipulated only with VAX BASIC Run-Time Library support 
routines. Most array descriptors created by VAX BASIC describe the actual 
data in an array. Some arrays, however, have elements that differ in 
length from one another. VAX BASIC arrays of this type include both 
dynamic string arrays and arrays of any datatype which have appeared 

in MAP DYNAMIC and REMAP statements. An array descriptor for an 
array of this type describes an array of element descriptors. One element 
descriptor exists for each array element and points to the actual data. 


As shown in Figure 19-8, VAX BASIC array descriptors consist of three 
blocks of information. The first block, the prototype block, is always four 
longwords in length. The second and third blocks, the multiplier and 
bounds blocks, vary in length depending on the number of dimensions for 
the array being described. The sections following the figure describe each 
block. 
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Figure 19-8: Array Descriptor Format 
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19.5.1 The Prototype Block 


In the prototype block, if the data type is not aligned bit string or packed 
decimal string, the first word of the first longword contains a value 
denoting the number of bytes in each array element. 


The length of an aligned bit string array element is specified in bits. The 
length of a packed decimal string array element is the number of 4-bit 
digits, not including the sign. 
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For arrays requiring a descriptor for each element, the value in this field 
is the length of the descriptor for the element. Dynamic string arrays 
and most remapped arrays require 8 bytes for the element descrip- 

tor. Remapped packed decimal arrays require 12 bytes for the element 
descriptor. 
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The third byte of the first longword contains a code indicating the 
VAX/VMS data type of the array described by the descriptor. For ar- 
rays requiring element descriptors, the value is 24 (the VAX/VMS literal 
DSC$K_DTYPE_DSC and the value 18 hexadecimal). For other arrays, 
the value reflects the actual data type of the array. The fourth byte de- 
notes the class of the array descriptor and will always have the value 4 
(DSC$K_CLASS_A). 


The second longword is a pointer containing the address of the first 
element of the array or the first element descriptor. The first byte of the 
third longword contains a scale factor for packed decimal arrays and for 
DOUBLE arrays in programs compiled with a scale factor. The second 
byte specifies the number of digits in each packed decimal array element; 
for array types other than packed decimal, this byte is zero. The third 
byte contains array flags indicating that the multiplier and bounds blocks 
are present (Hexadecimal DO). The fourth byte contains a value equal to 
the number of dimensions in the array. The fourth longword contains the 
total size of the array in bytes. 


19.5.2 The Multiplier Block 


For arrays where all dimensions have a lower bound of zero, the first 
longword (A0) of the multiplier block has the same value as the second 
longword of the prototype block (the pointer). For arrays with dimensions 
that possess nonzero lower bounds, the value of AO is the address of the 
first array element adjusted to account for the non-zero lower bounds in 
all dimensions. You can use this field in the descriptor to access arrays 
without consideration of the lower bounds of the array dimensions when 
computing the element address. 


The multiplier block contains an additional longword for each dimension 
of the array. Each longword contains the number of elements in the 
corresponding dimension (the upper bound minus the lower bound 

plus 1). 


19.5.3 The Bounds Block 


The third block, the bounds block, consists of one longword pair for each 

dimension of the array. The first longword of each pair specifies the lower 
bound of the corresponding dimension and the second longword specifies 

the upper bound of that dimension. 


Data Representation 19-11 


19.6 Decimal Scalar String Descriptor (Packed Decimal String 
Descriptor) 


A single descriptor form gives decimal size and scaling information for 
both scalar data and simple strings. See Figure 19-9. 


Figure 19-9: Decimal Scalar String Descriptor 


eT [men 
POINTER 
RESERVED DIGITS | SCALE 


ZK-5181-86 












For packed decimal strings, the length field contains the number of 4-bit 
digits (not including the sign). The pointer field contains the address 

of the first byte in the packed decimal string. The scale field contains a 
signed power-of-ten multiplier to convert the internal form to the external 
form. For example, if the internal number is 123 and the scale field is 
+1, then the external number is 1230. The digits field is 0; the number of 
digits is computed from the length field. The reserved field must be zero. 
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Chapter 20 


Advanced File Input and Output 


This chapter describes some of the more advanced I/O features available 
in VAX BASIC. For more information on I/O to RMS disk files, see 
Chapter 15 in this manual. 


20.1 Introduction 


This chapter discusses the following topics: 


e RMS I/O to ANSI magnetic tapes 


e Device-specific I/O to magnetic tapes (including TK50 devices), disks, 
and unit record devices 


¢ I/O to mailboxes 
e Network I/O 


When you do not specify a file name in the OPEN statement, the I/O 
you perform is said to be device-specific. This means that read and write 
operations (GET and PUT statements) are performed directly to or from 
the device. For example: 


OPEN "MTA2:" FOR OUTPUT AS FILE #1 
OPEN "MTA1:PARTS.DAT" FOR INPUT AS FILE #2, SEQUENTIAL 


Because the file specification in the first line does not contain a file name, 
the OPEN statement opens the tape drive for device-specific I/O. The 
second line opens an ANSI-format tape file using RMS because a file 
name is part of the file specification. 


The following sections describe both I/O to ANSI-format magnetic tapes 
and device-specific I/O to magnetic tape, unit record, and disks devices. 
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20.2 RMS 1/0 to Magnetic Tape 


VAX BASIC supports I/O to ANSI-formatted magnetic tapes. When 
performing I/O to ANSI-formatted magnetic tapes, you can read or write 
to only one file to a magnetic tape at a time, and the files are not available 
to other users. ANSI tape files are RMS sequential files. 


20.2.1 Allocating and Mounting a Tape 
You should allocate the tape unit to your process before starting file 
operations. For example: 
$ ALLOCATE MT1: 


This command assigns tape drive MT1: to your process. You must also 
set the tape density and label with the MOUNT command. Optionally, 
you can specify a logical name to assign to the device, in this case, TAPE. 


$ MOUNT/DENSITY=1600 MT1: VOLOO1 TAPE 
When mounting a TK50, you cannot specify a density. 


If the records do not specify the size of the block (no value in HDR 2), 
specify the BLOCKSIZE as part of the MOUNT command. For example: 


$ MOUNT/DENSITY=1600/BLOCKSIZE=128 MT1: VOLO20 TAPE 


Alternatively, you can use the $MOUNT system service to mount tapes. 


20.2.2 Opening a Tape File for Output 


To create and open a magnetic tape file for output, you use the 
OPEN statement. For instance, the following statement opens the file 
PARTS.DAT and writes 256 byte records that are blocked four to a 
physical tape block of 1024 bytes. 


OPEN "MT1:PARTS.DAT" FOR OUTPUT AS FILE #2%, SEQUENTIAL FIXED, & 
RECORDSIZE 256%, BLOCKSIZE 4% 


Specifying FIXED record format creates ANSI F format records. Specifying 
VARIABLE creates ANSI D format records. If you do not specify a record 
format, the default is VARIABLE. 
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NOTE 


Every record in an ANSI D formatted file is prefixed by a 4-byte 
header giving the record length in decimal ASCII digits. The 
length includes the 4-byte header. VAX BASIC adds the 4-byte 
header to the record size when calculating block size. The 
header is transparent to your program. 


If you do not specify a block size, VAX BASIC defaults to one record per 
block. For small records, this can be inefficient; the tape will contain many 
inter-record gaps. 


20.2.3 Opening a Tape File for Input 


To open an existing magnetic tape file, you also use the OPEN statement. 
For example, the following statement opens the file PAYROLL.DAT. If you 
do not specify a record size or a block size, VAX BASIC defaults to the 
values in the header block. If you do not specify a record format, VAX 
BASIC defaults to the format present in the header block (ANSI F or ANSI 
D). You must specify ACCESS READ if the tape is not write-enabled. For 
example: 


100 


OPEN "TAPE:PAYROLL.DAT" FOR INPUT AS FILE #4% 
, ACCESS READ 


20.2.4 Positioning a Tape 


NOREWIND positions the tape for reading and writing as follows: 


Specifying NOREWIND when you create a file positions the tape at 
the logical end-of-tape and leaves the unit open for writing. If you 
omit NOREWIND, you start writing at the beginning of the tape 
(BOT), logically deleting all subsequent files. 


Specifying NOREWIND when you open an existing file starts a search 
for the file at the current position. The search continues to the logical 
end-of-tape. If the record is not found, VAX BASIC rewinds and 
continues the search until reaching the logical end-of-tape again. 
Omitting NOREWIND tells VAX BASIC to rewind the tape and search 
for the file name until reaching the end-of-tape. In either case, you 
receive an error message if the file does not exist. 
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For example, the following statement opens PAYROL.DAT after advancing 
the tape to the logical end-of-tape. If you omit NOREWIND, the file 
opens at the beginning of the tape, logically deleting all subsequent files. 


OPEN "MT1:PAYROL.DAT" FOR OUTPUT AS FILE #1% & 
»ORGANIZATION SEQUENTIAL, NOREWIND 


Note that you cannot specify REWIND; to avoid rewinding the tape, omit 
the NOREWIND keyword. 


20.2.5 Writing Records to a File 


The PUT statement writes sequential records to the file. The following 
program writes a record to the file. Successive PUT operations write 
successive records. 


Example 


OPEN “MTO:TEST.DAT" FOR OUTPUT AS FILE #2, & 
SEQUENTIAL FIXED, RECORDSIZE 20% 
B$ = "" 
WHILE B$ <> "NO" 
LINPUT "Name"; A$ 
MOVE TO #2, A$ = 20 
PUT #2 
LINPUT "Write another record"; B$ 
NEXT 
CLOSE #2 
END 


Each PUT writes one record to the file. If your OPEN statement specifies 
a RECORDSIZE clause, the record buffer length equals RECORDSIZE or 
the map size. For example: 


RECORDSIZE 60% 


This clause specifies a record length and a record buffer size of 60 bytes. 
You can specify a record length between 18 and 8192 bytes. The default 
is 132 bytes. 


If you specify a MAP clause and no RECORDSIZE clause, then the record 
size is the size of the map. 


If you also specify BLOCKSIZE, the size of the buffer equals the value in 
BLOCKSIZE multiplied by the record size. For example: 


RECORDSIZE 60%, BLOCKSIZE 4% 
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These clauses specify a logical record length of 60 bytes and a physical 
tape record size of 240 bytes (60 * 4). You specify BLOCKSIZE as an 
integer number of records. RMS rounds the resulting value to the next 
multiple of four. The total I/O buffer length cannot exceed 8192 bytes. 
The default is a buffer (tape block) containing one record. 


To write true variable-length records, use the COUNT clause with the 
PUT statement to specify the number of bytes of data written to the 
file. Without COUNT, all records equal the length specified by the 
RECORDSIZE clause when you opened the file. 


20.2.6 Reading Records from a File 


The GET statement reads one logical record into the buffer. For example, 
in the following program, the first GET reads a group of four records 

(a total of 80 bytes) from the file on channel #5 and transfers the first 

20 bytes to the record buffers. Successive GET operations read 20 byte 
records to the record buffer performing an I/O to the tape every 4 records. 


Example 


OPEN "MTO:TEST.DAT" FOR INPUT AS FILE #5%, & 
ORGANIZATION SEQUENTIAL FIXED, RECORDSIZE 20%, & 
BLOCKSIZE 4%, ACCESS READ 

B$ - wn 

WHILE B$ <> "NQ" 

GET #5 

MOVE FROM #5, A$ = 20 

PRINT A$ 

LINPUT "Do you want another record"; B$ 

NEXT 

CLOSE #5 

END 


20.2.7 Controlling Tape Output Format 


Magnetic tape physical records range from 18 to 8192 bytes. With RMS 
tapes, you can optionally specify this size in the BLOCKSIZE clause as a 
positive integer indicating the number of records in each block. 

VAX BASIC then calculates the actual size in bytes. Thus, a fixed-length 
file on tape with 126 byte records can have a block size between 1 and 64, 
inclusive. The default is 126 bytes (one record per block). 
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For instance, in the following example of an OPEN statement, the 
RECORDSIZE clause defines the size of the records in the file as 90 
bytes, and BLOCKSIZE defines the size of a block as 12 records (1080 
bytes). Thus, your program contains an I/O buffer of 1080 bytes. Each 
physical read or write operation moves 1080 bytes of data between the 
tape and this buffer. Every twelfth GET or PUT operation causes a phys- 
ical read or write. The next eleven GET or PUT operations only move 
data into or out of the I/O buffer. Specifying a block size larger than the 
default can reduce overhead by eliminating some physical reading and 
writing to the tape. In addition, specifying a large block size conserves 
space on the tape by reducing the number of inter-record gaps (IRGs). In 
the example, a block size of 12 saves time by accessing the tape only after 
every twelfth record operation. 


OPEN "MTO: [SMITH] TEST.SEQ" FOR OUTPUT AS FILE #12% & 
,ORGANIZATION SEQUENTIAL FIXED, RECORDSIZE 90% & 
,BLOCKSIZE 12% 


Through RMS, VAX BASIC controls the blocking and deblocking of 
records. RMS checks each PUT operation to see if the specified record 
fits in the tape block. If it does not, RMS fills the rest of the block with 
circumflexes (blanks) and starts the record in a new block. Records cannot 
span blocks in magnetic tape files. 


When you read blocks of records, your program can issue successive GET 
statements until it locates the fields of the record you want. For example, 
the following program finds and displays a record on the terminal. You 
can invoke the RECOUNT function to determine how many bytes were 
read in the GET operation. 

Example 

MAP (XXX) NA.ME$ = 5%, address$ = 20% 


OPEN "MTO:FILE.DAT" FOR INPUT AS FILE #4%, & 
SEQUENTIAL FIXED, MAP XXX, ACCESS READ 


NA.ME$ = "" 
GET #4 UNTIL NA.ME$ = "JONES" 
PRINT NA.ME$; "LIVES AT "; address$ 


CLOSE #4 
END 
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20.2.8 Rewinding a Tape 


With the RESTORE # statement, you can rewind the tape to the start of 
the currently open file. 
Example 


OPEN "MTO:FTF.DAT" FOR INPUT AS FILE #2%, ACCESS READ 
GET #2% 


RESTORE #2% 
GET #2% 


You cannot rewind past the beginning of the currently open file. 


20.2.9 Closing a File 
The CLOSE statement ends I/O to the file. For example, the following 
statement ends input and output to the file open on channel #6. 
CLOSE #67, 


If you opened the file with ACCESS READ, CLOSE has no further effect. 
If you opened the file without specifying ACCESS READ and the tape is 
not write-locked (that is, if the plastic write ring is in place), VAX BASIC 
does the following: 


e Writes file trailer labels and two end-of-file marks following the last 
record 


e Backspaces over the last end-of-file mark 


VAX BASIC does not rewind the tape. 


20.3 Device-Specific I/0 


Device-specific I/O lets you perform I/O directly to a device. The follow- 
ing sections describe device-specific I/O to unit record devices, tapes, and 
disks. 
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20.3.1 Device-Specific 1/0 to Unit Record Devices 


You perform device-specific I/O to unit record devices by using only the 
device name in the OPEN statement file specification. You should allocate 
the device at DCL command level before reading or writing to the device. 
For example, this command allocates a card reader: 


$ ALLOCATE CR1: 


Once the device is allocated, you can read records from it: 


Example 


MAP (DNG) A% = 80% 
OPEN "CRi:" FOR INPUT AS FILE #1%, ACCESS READ, MAP DNG 
GET #1% 


VAX BASIC treats the device as a file, and data is read from the card 
reader as a series of fixed-length records. 


20.3.2 Device-Specific 1/0 to Magnetic Tape Devices 


When performing device-specific I/O to a tape drive, you open the 
physical device and transfer data between the tape and your program. 
GET and PUT statements perform read and write operations. UPDATE 
and DELETE statements are invalid when you perform device-specific 
1/O. 


20.3.2.1 Allocating and Mounting a Tape 


You must allocate the tape unit to your process before starting file opera- 
tions. For example, the following command line assigns tape drive MT1: 
to your process. 


$ ALLOCATE MT1: 


Use the DCL command MOUNT and the /FOREIGN qualifier to mount 
the tape. For example: 


$ MOUNT/FOREIGN MT1: 


If your program needs a blocksize other than 512 bytes, or a particular 
tape density, specify these characteristics with the MOUNT command as 
well. For example: 


$ MOUNT/FOREIGN/BLOCKSIZE=1024/DENSITY=1600 MT1: 
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When reading a foreign tape, you must make sure the /BLOCKSIZE 
qualifier has a value at least as large as the largest record on the tape. 


20.3.2.2 Opening a Tape File for Output 


To create and open the magnetic tape file for output, you use the OPEN 
statement. For example, the following statement opens tape drive MT1: 
for writing. It is important to use the SEQUENTIAL VARIABLE clause 
unless the records are fixed. In contrast to ANSI tape processing, RMS 
does not write record length headers or variable-length records to foreign 
tapes. If you specify SEQUENTIAL VARIABLE, you should have some 
way to determine where records begin and end. 


OPEN "MTi:" FOR OUTPUT AS FILE #1%, & 
ORGANIZATION SEQUENTIAL VARIABLE 


20.3.2.3 Opening a Tape File for Input 


To access a tape with existing data, you also use the OPEN statement. For 
example, the following statement opens the tape unit MT2:. 


OPEN "MT2:" AS FILE #2% 


Depending on how you access records, there are two ways to open a 
foreign magnetic tape. If your program uses dynamic buffering and MOVE 
statements, open the file with no RECORDSIZE clause. RMS will provide 
the correct buffer size for VAX BASIC. Do not specify a BLOCKSIZE value 
or ORGANIZATION clause with the OPEN statement. 


If your program uses MAP and REMAP statements, but you do not know 
how long the records are, specify a MAP that is as large as the value you 
specified for the /BLOCKSIZE qualifier when mounting the tape. Do not 
specify a BLOCKSIZE value or ORGANIZATION clause with the OPEN 
statement. 


When processing records, each GET operation will read one physical 
record whose size is returned in RECOUNT. If you are using a map only, 
the first n bytes (where n is the value returned in RECOUNT) are valid. 
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20.3.2.4 Writing Records to a File 
The PUT statement writes records to the file in sequential order. 


Example 


OPEN "MTO:" FOR OUTPUT AS FILE #9%, & 
SEQUENTIAL VARIABLE 

INPUT "NAME"; NA.ME$ 

MOVE TO #9%, NA.ME$ 

PUT #9% 


The last line writes the contents of the record buffer to the device. 
Successive PUT operations write successive records. 


The default record length (and therefore, the size of the buffer) is 132 
bytes. The RECORDSIZE attribute causes VAX BASIC to read or write 
records of a specified length. For instance, the following statement opens 
tape unit MTO: and specifies records of 900 characters. You must specify 
an even integer larger than or equal to 18. If you specify a buffer length 
less than 18, VAX BASIC signals an error. If you try to write a record 
longer than the buffer, VAX BASIC signals the error “Size of record 
invalid” (ERR = 156). 


OPEN "MTO:" FOR INPUT AS FILE #1%, RECORDSIZE 900% 


To write records shorter than the buffer, include the COUNT clause with 
the PUT statement. For example, the following statement writes a 
56-character record to the file open on channel #6. If you do not specify 
COUNT, VAX BASIC writes a full buffer. You can specify a minimum 
count of 18, and a maximum count equal to the buffer size. When writing 
records to a foreign magnetic tape, neither VAX BASIC nor RMS prefixes 
the records with any count bytes. 


PUT #6%, COUNT 56% 


20.3.2.5 Reading Records from a File 


The GET statement reads records into the buffer. For instance, the fol- 
lowing program reads a record into the buffer, prints a string field, and 
rewinds the file before closing. Successive GET operations read successive 
records. VAX BASIC signals the error “End of file on device” (ERR = 11) 
if you encounter a tape mark during a GET operation. If you trap this 
error and continue, you can skip over any tape mark(s). The system vari- 
able RECOUNT is set to the number of bytes transferred after each GET 
operation. 
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Example 


OPEN "MT1:" FOR INPUT AS FILE #1%, ACCESS READ 
GET #1% 

MOVE FROM #1%, A$ = RECOUNT 

PRINT A$ 

RESTORE #1% 

CLOSE #1% 


20.3.2.6 Rewinding a Tape 


When you mount a magnetic tape, the system will position the tape at 
the load point (BOT). Your program can rewind the tape during program 
execution with the RESTORE statement. 


Example 
OPEN "MT1:" FOR OUTPUT AS FILE #2%, ACCESS READ 


PUT #2%, 
RESTORE #2% 
INPUT "NEXT RECORD"; NXTRECBBY 


If you rewind a tape opened without ACCESS READ before closing it, you 
erase all data written before the RESTORE operation. 


20.3.2.7 Closing a Tape 


The CLOSE statement ends I/O to the tape. For example, the following 
statement ends input and output to the tape open on channel #12. 


CLOSE #12% 


If you opened the file with ACCESS READ, CLOSE has no further effect. 
If you opened the file without specifying ACCESS READ and the tape is 
not write-locked (that is, if the plastic write ring is in place), VAX BASIC 
does the following: 


e Writes file trailer labels and two end-of-file marks following the last 
record 


e Backspaces over the last end-of-file mark 


The tape is not rewound unless you specified RESTORE in your program. 
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20.3.3 Device-Specific 1/0 to Disks 


When performing device-specific I/O to disks, you write and read data 
with PUT and GET statements. The data must fit in 512-byte blocks, and 
you must do your own blocking and deblocking with MAP/REMAP or 
MOVE statements. Note that, when accessing disks with device-specific 
I/O operations, you are performing logical I/O. Because of this, you 
should be careful not to overwrite block number zero, which is often the 
disk’s boot block. You must have LOG_IO privileges to perform these 
operations. 


The following sections describe device-specific I/O to disks. 


20.3.3.1 Assigning and Mounting a Disk 


You must allocate a disk unit to your process before starting operations. 
For example, the following command line assigns disk DUA3: to your 
process. 


$ ALLOCATE DUA3: 


When you perform I/O directly to a disk, you must mount the disk with 
the MOUNT command before accessing it. For example: 


$ MOUNT/FOREIGN DUA3: 


You can then open the disk for input or output. 


20.3.3.2 Opening a Disk File for Output 


To create and open the disk file, you use the OPEN statement. For 
example: 


OPEN "DUA3:" FOR OUTPUT AS FILE #2%, SEQUENTIAL FIXED, & 
RECORDSIZE=512 


You can then write data to the disk. 


The record size determined by the MAP or RECORDSIZE clause must be 
an integer multiple of 512 bytes. 
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20.3.3.3 Opening a Disk File for Input 


To open an existing disk file, you also use the OPEN statement. For 
example: 


OPEN "DUA1:" FOR INPUT AS FILE #4%, SEQUENTIAL FIXED, & 
RECORDSIZE=612 


You can then read data from the disk. 


The recordsize determined by the MAP or RECORDSIZE clause must be 
an integer multiple of 512 bytes. The default is 512. 


Specify ACCESS READ in the OPEN statement if you only plan to read 
from the disk. 


20.3.3.4 Writing Records to a Disk File 


You write data by defining a record buffer and writing the data to the file 
with PUT statements. For example, the following program writes eight 64 
byte records into each 512-byte block on the disk. When your program 
fills one block, writing continues in the next. The FILL field in the MOVE 
statement positions the data in the block. 


Example 


INPUT "HOW MANY RECORDS TO WRITE"; J% 
OPEN "DBB2: FOR OUTPUT AS FILE #2%, SEQUENTIAL FIXED, & 
RECORDSIZE=512 
FOR K% = 1% TO J% 
FOR I% = 0% TO 7% 
INPUT "NAME OF BOOK"; BOOK_NAME$ 
INPUT "RETRIEVAL NUMBER"; RET_NUM% 
INPUT "SUBJECT AREA"; SUBJ$ 
MOVE TO #2%, FILL$ = I% * 64%, BOOK_NAME$, RET_NUM%, SUBJ$ 
NEXT I% 
PUT #2% 
NEXT K% 
CLOSE #2 


When you write records, VAX BASIC does not prefix the records with any 
count bytes. 
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20.3.3.5 Reading Records from a Disk File 


You read data by defining a record buffer and reading the data from the 
device with GET statements. After the data has been retrieved with a GET 
statement you can deblock the data with MOVE or REMAP statements. 


In the following example, each disk block contains twelve 40-byte records. 
Each record contains a 32-byte string, a 4-byte SINGLE number, and a 
4-byte LONG integer. After each GET operation, the FOR...NEXT loop 
uses the REMAP statement to redefine the position of the variables in the 
record. At the end of the file, the program closes the file. See Chapter 9 
and the VAX BASIC Reference Manual for more information on the MAP, 
MAP DYNAMIC and REMAP statements. 


Example 


MAP (SAM) FILL$ = 512 
MAP DYNAMIC (SAM) STRING PRT_ID, SINGLE MAFLD, LONG ADIR_OLDN 
OPEN "DUA1:" FOR INPUT AS FILE #2%, SEQUENTIAL FIXED, & 
ACCESS READ, MAP SAM 

WHEN ERROR USE err_hand 
WHILE 1% = 1% 

GET #2% 

FOR I% = 0% TO 11% 

REMAP (SAM) STRING FILL(I% * 40%), PRT_ID = 32, MAFLD, ADIR_OLDN 
PRINT PRT_ID, MAFLD, ADIR_OLDN 

NEXT I% 
NEXT 
END WHEN 
HANDLER err_hand 

IF ERR <> 11% 
THEN 
EXIT HANDLER 
END IF 

END HANDLER 
CLOSE #2% 
END 


20.4 1/0 to Mailboxes 


A mailbox is a record I/O device that passes data from one process to 
another. You can use a valid mailbox name as a file name, and treat that 
mailbox as a normal record file. You must have TMPMBX or PRMMBX 
privilege to create mailboxes. Mailboxes are created and deleted by system 
services. For more information on using system services in VAX BASIC 
programs, see Chapter 21 in this manual. 
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Use the EXTERNAL statement to define the SYS$CREMBX system service 
that creates the mailbox. In VAX BASIC programs, you create mail- 
boxes by invoking SYS$CREMBX as a function passing either a channel 
argument and a string literal or a logical name for the mailbox. For 
example: 


EXTERNAL INTEGER FUNCTION SYS$CREMBX 
SYS$STATUS%, = SYS$CREMBX(,CHAN%,,,,,"CONFIRMATION_MBX") 


If you supply a logical name for the mailbox, be sure that it is in uppercase 
letters. Once you create the mailbox, you can use it as a logical file name. 


The following two examples, when executed on two separate processes, 
allow you to send and receive data from one process to another. 


Example 1 


DECLARE STRING passenger_name, Confirm_msg 

OPEN "CONFIRMATION_MBX" AS FILE #1% 

INPUT "WHAT IS THE PASSENGER NAME"; passenger_name 
PRINT #1%, passenger_name 

LINPUT #1%, confirm_msg 

PRINT confirm_nsg 

END 


Example 2 


MAP (res) STRING passenger_name = 32% 
DECLARE WORD mbx_chan, LONG sys_status 
EXTERNAL LONG FUNCTION sys$crembx (LONG, WORD, LONG, LONG, & 
LONG, LONG, STRING) 
WHEN ERROR USE err_trap 
sys_status = sys$crembx ( ,mbx_chan,,,,,"CONFIRMATION_MBX") 
OPEN "CONFIRMATION_MBX" FOR INPUT AS FILE #1% 
LINPUT #1%, passenger_name 
OPEN "RESER.LST" FOR INPUT AS FILE #2%, & 
ORGANIZATION INDEXED, MAP RES, ACCESS READ & 
PRIMARY passenger_name 
FIND #2%, KEY #0% EQ passenger_name 
RECEIVING .MSG$ = "Passenger reservation confirmed" 
PRINT #1%, RECEIVING .MSG$ 
END WHEN 
HANDLER err_trap 
IF (ERR = 155) 
THEN 
RECEIVING .MSG$ = "Reservation does not exist" 
ELSE 
EXIT HANDLER 
END IF 
END HANDLER 
CLOSE #2%, #1% 
END PROGRAM 
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Example 1 requests a passenger name and sends it to the mailbox. 
Example 2 looks up the name in an indexed file. If the passenger name 
exists, Example 2 writes the confirmation message to the mailbox. If 
the passenger name does not exist, the error handler writes an alternate 
message. Example 1 then reads the mailbox and returns the result. 


VAX BASIC treats the mailbox as a sequential file. You write to the file 
with the PRINT # or PUT statement, and read it with the INPUT #, 
LINPUT #, or GET statement. 


When either program closes the mailbox, the other program receives an 
end-of-file error message when it attempts to read the mailbox. 


NOTE 


All mailbox operations are synchronous. Control does not pass 
back from a mailbox operation, such as a PUT, to your program 
until the other program completes the corresponding operation, 
such as a GET. 


20.5 Network 1/0 


If your system supports DECnet-VAX facilities, and your computer is one 
of the nodes in a DECnet-VAX network, you can communicate with other 
nodes in the network with VAX BASIC program statements. VAX BASIC 
lets you do the following: 


¢ Read and write files on a remote node as you do files on your own 
system (remote file access) 


e Exchange data with a process executing at a remote location (task-to- 
task communication) 
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20.5.1 Remote File Access 


To write or read files at a remote site, include the node name as part of 
the file specification. For example: 


OPEN "WESTON: :DUA1: [HOLT]TEST.DAT;2" FOR INPUT AS FILE #2% 


You can also assign a logical name to the file specification, and use that 
logical name in all file I/O. 


NOTE 
You need NETMBX privileges to access files at a remote node. 


If the account at the remote site requires a username and password, 
include this access string in the file specification. You do this by enclosing 
the access string in quotation marks and placing it between the node 
name and the double colon. For example, the following file specification 
accesses the account [HOLT.TMP] on node WESTON by giving the 
username HOLT and the password PASWRD. After accessing the file, 
your VAX BASIC program can read and write records as if the file were in 
your account. 


OPEN 'WESTON"HOLT PASWRD": :DUAO: [HOLT. TMP] INDEXU.DAT;4' & 
FOR INPUT AS FILE #1%, INDEXED, PRIMARY TEXT$ 


20.5.2 Task-to-Task Communication 


VAX BASIC supports task-to-task communication if your account has 
NETMBXxX privileges. 


Follow these steps for task-to-task communication: 


1. Establish a command file at the remote site to execute the program you 
want. The program must be in executable image format. For example, 
you can create the file MARG.COM at the remote site. MARG.COM 
contains a line to run an image (in this case, COPYT.EXE): 


$ RUN COPYT 


The OPEN statements in the programs at both nodes must specify the 
same file attributes. 
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2. Start task-to-task communication by accessing the command file at the 
remote site. For example, a program at the local node could contain 
the following line: 


OPEN 'WESTON:: "TASK = MARG"' AS FILE #1%, SEQUENTIAL 


3. The system then assigns the logical name SYS$NET to the program at 
the local node. At the remote node, the program (COPYT.EXE) must 
use this logical for all operations. For example: 


OPEN 'SYS$NET' FOR INPUT AS FILE #1%, SEQUENTIAL 


4. The two programs can then exchange messages. The programs must 
have a complementary series of send/receive statements. 


Example 


!Local Program 
MAP (SJK) MSG$ = 32% 
OPEN 'WESTON"DAVIS PSWRD":: "TASK = MARG"' & 
FOR OUTPUT AS FILE #1%, SEQUENTIAL, MAP SJK 
LINPUT "WHAT IS THE CUSTOMER NAME"; MSG$ 
PUT #1% 
GET #1%, 
PRINT MSG$ 
CLOSE #1% 
END 


!Remote Node Program 


10 MAP (SJK) MSG$ = 32% 
MAP (FIL) NAME$ = 32%, RESERVATION$ = 64%, 
OPEN 'SYS$NET' FOR INPUT AS FILE #1%, SEQUENTIAL, & 
MAP SJK 
OPEN 'RESER.DAT'FOR INPUT AS FILE #2%, & 
INDEXED FIXED, PRIMARY NAME$, MAP FIL 
GET #14, 
MSG$ = "NAME CONFIRMED" 
WHEN ERROR IN 
100 FIND #2%, KEY 0% EQ MSG$ 
USE 
IF ERR = 153 
THEN 
MSG$ = "ERROR IN NAME" 
ELSE 
EXIT HANDLER 
END IF 
END WHEN 
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PUT #14, 


CLOSE #2%, 1% 
END 


The task-to-task communication ends when the files are closed. 


See the VAX/VMS Networking Manual and the VAX/VMS System Manager's 
Reference Manual for more information. 
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Chapter 21 


Using VAX BASIC in the Common 
Language Environment 


The VAX BASIC compiler lets you call external routines from a VAX 
BASIC program. This chapter shows you how to call the following from 
VAX BASIC: 


e External routines written in other VAX languages 
¢ VAX/VMS Run-Time Library routines 
e VAX/VMS system services 


The terms routine, procedure, and function are used throughout this 
chapter. A routine is a closed, ordered set of instructions that performs 
one or more specific tasks. Every routine has an entry point (the routine 
name), and may or may not have an argument list. Procedures and 
functions are specific types of routines: a procedure is a routine that does 
not return a value, while a function is a routine that returns a value by 
assigning that value to the function’s identifier. 


System routines are prewritten VAX/VMS routines that perform common 
tasks such as finding the square root of a number or allocating virtual 
memory. You can call any system routine from VAX BASIC provided that 
the data structures necessary for that routine are supported. The system 
routines used most often are VAX/VMS Run-Time Library routines and 
system services. System routines, which are discussed later in this chapter, 
are documented in detail in the VAX/VMS Run-Time Library Routines 
Reference Manual and the VAX/VMS System Services Reference Manual. 
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21.1 Specifying Parameter-Passing Mechanisms 


When you pass data between routines that are not written in the same 
VAX language, you have to specify how you want that data to be rep- 
resented and interpreted. You do this by specifying a parameter-passing 
mechanism. The three general parameter-passing mechanisms and their 
keywords in VAX BASIC are as follows: 


¢ By reference—BY REF 


e By descriptor—BY DESC 
e By value—BY VALUE 


The following sections outline each of these parameter-passing mecha- 
nisms in more detail. 


21.1.1 Passing Parameters by Reference 


When you pass a parameter by reference, VAX BASIC passes the address 
at which the actual parameter value is stored. In other words, your 
routine has access to the parameter’s storage address; therefore, you can 
manipulate and change the value of this parameter. Any changes that you 
make to the value of the parameter in your routine are reflected in the 
calling routine as well. 


21.1.2 Passing Parameters by Descriptor 


A descriptor is a data structure that contains the address of a parameter, 
along with other information such as the parameter’s data type and size. 
When you pass a parameter by descriptor, the VAX BASIC compiler 
passes the address of a descriptor to the called routine. You usually use 
descriptors to pass parameters that have unknown lengths, such as the 
following: 


e Character strings 
e = Arrays 
e Compound data structures 


Like parameters passed by reference, any change made to the value of a 
parameter passed by descriptor is reflected in the calling routine. 
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21.1.3 Passing Parameters by Value 


When you pass a parameter by value, you pass a copy of the parameter 
value to the routine instead of passing its address. Because the actual 
value of the parameter is passed, the routine does not have access to 

the storage location of the parameter; therefore, any changes that you 
make to the parameter value in the routine do not affect the value of that 
parameter in the calling routine. 


21.1.4 VAX BASIC Default Parameter-Passing Mechanisms 


There are default parameter-passing mechanisms established for every 
data type you can use with VAX BASIC. Table 21-1 shows which VAX 
BASIC data types you can use with each parameter-passing mechanism. 


Table 21-1: Allowable Parameter-Passing Mechanisms 


Parameter BY VALUE BY REF BY DESC 
_ Integer and Real Data 

Ne ne ooo 

Variables Yes Yes Yes 

Constants Yes Local Local 
copy! copy 

Expressions Yes Local Local 
copy copy 

Elements of a Yes Yes! Yes 

nonvirtual array 

Virtual Yes Local Local 

array elements copy! copy 

Nonvirtual No Yes Yes! 

entire array 

Virtual No No No 


entire array 





‘Specifies the default parameter-passing mechanism. 
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Table 21-1 (Cont.): Allowable Parameter-Passing Mechanisms 


Parameter BY VALUE BY REF BY DESC 

Packed Decimal Data 

Variables No Yes! Yes 

Constants No Local Local 
copy! copy 

Expressions No Local Local 
copy! copy 

Nonvirtual No Yes! Yes 

array elements 

Virtual No Local Local 

array elements copy! copy 

Nonvirtual No Yes Yes! 

entire arrays 

Virtual No No No 


entire arrays 


String Data 


of] 
Variables No Yes Yes 
Constants No Local Local 
copy copy! 
Expressions No Local Local 
copy copy! 
Nonvirtual No Yes Yes! 
array elements 
Virtual No Local Local 
array elements copy copy! 
Nonvirtual No Yes Yes! 
entire arrays 
Virtual No No No 


entire arrays 


Other Parameters 


SS eS 
RECORD variables No Yes No 
RFA variables No Yes! No 


Specifies the default parameter-passing mechanism. 
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21.1.5 Creating Local Copies 


If a parameter is an expression, function, or virtual array element, then it 
is not possible to pass the parameter’s address. In these cases, VAX BASIC 
makes a local copy of the parameter’s value and passes this local copy by 
reference. 


You can force VAX BASIC to make a local copy of any parameter by 
enclosing the parameter in parentheses. Forcing VAX BASIC to make a 
local copy is a useful technique because you make it impossible for the 
subprogram to modify the actual parameter. In the following example, 
when variable A is printed in the main program, the value is zero because 
the variable A is not modifiable by the subprogram. 


Example 


DECLARE LONG A 
CALL SUB1 ((A)) 
PRINT A 

END 


SUB SUBi (LONG B) 
B= 3 

END SUB 
Output 


0 


By removing the extra parentheses from A, you allow the subprogram to 
modify the parameter. 
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Example 


DECLARE LONG A 
CALL SUB1 (A) 
PRINT A 

END 


SUB SUB1 (LONG B) 
B= 3 

END SUB 
Output 


3 


21.2 Calling External Routines 


Most of the steps of calling external routines are the same whether you 
are calling an external routine written in VAX BASIC, an external routine 
written in some other VAX language, a system service, or a VAX/VMS 
Run-Time Library routine. The following sections outline the procedure 
for calling non-BASIC external routines. For information on calling BASIC 
routines, see Chapter 14. 


21.2.1 Determining the Type of Call 


Before you call an external routine, you must determine whether the call 
to the routine should be a function call or a procedure call. You should 
call a routine as a function if it returns any type of value. If the routine 
does not return a value, you should call it as a procedure. 


21.2.2 Declaring an External Routine and Its Arguments 


To call an external routine or system routine you need to declare it as an 
external procedure or function and to declare the names, data types, and 
passing mechanisms for the arguments. Arguments can be either required 
or optional. 


You should include the following information in a routine declaration: 


e The name of the external routine 
e The data types of all the routine parameters 
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e The passing mechanisms for all the routine parameters, provided that 
the routine is not written in VAX BASIC 


When you declare an external routine, use the EXTERNAL statement. This 
allows you to specify the data types and parameter-passing mechanisms 
only once. 


In the following example, the EXTERNAL statement declares cobsub as an 
external subprogram with two parameters: a LONG integer and a string 
both passed by reference. 


EXTERNAL SUB cobsub (LONG BY REF, STRING BY REF) 


With the EXTERNAL statement, VAX BASIC allows you to specify that 
particular parameters do not have to conform to specific data types and 
that all parameters past a certain point are optional. A parameter declared 
as ANY indicates that any data type can appear in the parameter position. 
In the following example, the EXTERNAL statement declares a SUB 
subprogram named allocate. This subprogram has three parameters: one 
LONG integer, and two that can be of any VAX BASIC data type. 


EXTERNAL SUB allocate(LONG, ANY,) 


A parameter declared as OPTIONAL indicates that all following param- 
eters are optional. You can have both required and optional parameters. 
The required parameters, however, must appear before the OPTIONAL 
keyword because all parameters following it are considered optional. 


In the following example, the EXTERNAL statement declares the Run- 
Time Library routine LIB;|LOOKUP_KEY. The keyword OPTIONAL is 
specified to indicate that the last three parameters can be optional. 


EXTERNAL LONG FUNCTION LIB$LOOKUP_KEY(STRING, LONG, OPTIONAL LONG, & 
STRING, INTEGER) 


For more information on using the EXTERNAL statement, see the VAX 
BASIC Reference Manual. 
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21.2.3 Calling the Routine 


Once you have declared an external routine, you can invoke it. To invoke 
a procedure, you use the CALL statement. To invoke a function, you use 
the function name in an expression. You must specify the name of the 
routine being invoked and all parameters required for that routine. Make 
sure the data types and passing mechanisms for the actual parameters you 
are passing match those you declared earlier, and those declared in the 
routine. 


If you do not want to specify a value for a required parameter, you 

can pass a null argument by inserting a comma as a placeholder in the 
argument list. If you are passing a parameter using a mechanism other 
than the default passing mechanism for that data type, you must specify 
the passing mechanism in the CALL statement or the function invocation. 


The following example shows you how to call the external subprogram 
allocate declared in Section 21.2.2. When allocate is called, it is called as a 
procedure. The first parameter must always be a valid LONG INTEGER 
value; the second and third parameters can be of any valid VAX BASIC 
data type. 


EXTERNAL SUB allocate(LONG, ANY,) 


CALL allocate (entity%, a$, 1%) 


This next example shows you how to call the Run-Time Library rou- 

tine LIBS|LOOKUP_KEY declared in Section 21.2.2. When the routine 
LIB$LOOKUP_KEY is called, it is invoked as a function. The first two 
parameters are required; all remaining parameters are optional. 


EXTERNAL LONG FUNCTION LIB$LOOKUP_KEY(STRING, LONG, OPTIONAL LONG, & 
STRING, INTEGER) 


ret_status% = LIB$LOOKUP_KEY(value$, point’) 


Note that if the actual parameter’s data type in the CALL statement does 
not match that specified in the EXTERNAL statement, VAX BASIC reports 
the compile-time informational message “Mode for parameter of routine 
changed to match declaration”. This tells you that VAX BASIC has made 
a local copy of the value of the parameter, and that this local copy has the 
data type specified in the EXTERNAL declaration. VAX BASIC warns you 
of this because the change means that the parameter can no longer 
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be modified by the subprogram. If VAX BASIC cannot convert the data 
type, VAX BASIC signals the error “Mode for parameter of routine not as 
declared”. 


The routine being called receives control, executes, and then returns con- 
trol to the calling routine at the next statement after the CALL statement 
or function invocation. 


VAX BASIC provides the built-in function LOC to allow you to access the 
address of a named external function. This is especially useful when pass- 
ing the address of a callback or AST routine to an external subprogram. 
In the following example, the address of the function compare is passed to 
the subprogram come_back_now using the LOC function. 


EXTERNAL LONG FUNCTION compare (LONG, LONG) 
EXTERNAL SUB come_back_now (LONG BY VALUE) 
CALL come_back_now (LOC(compare) BY VALUE) 


21.3 Calling VAX BASIC Subprograms from Other Languages 


When you call a VAX BASIC subprogram from another language, there are 
some additional considerations that you should be aware of. For instance, 
although VAX BASIC conforms to the VAX Procedure Calling Standard, 
you should specify explicit passing mechanisms when calling a routine 
written in another language. VAX BASIC’s default passing mechanisms 
may not match what the procedure expects. 


VAX FORTRAN passes and receives numeric data by reference; only the 
default parameter-passing mechanisms are required for passing numeric 
data back and forth between VAX FORTRAN and VAX BASIC programs. 


Both VAX BASIC and VAX FORTRAN pass strings by descriptor. 
However, VAX FORTRAN subprograms cannot change the length of 
strings passed to them. Therefore, if you pass a string to a VAX FORTRAN 
subprogram, you must make sure that the string is long enough to receive 
the result. You do this in one of two ways: 


e Pre-extend the string. Set the string variable equal to SPACE$(n), 
where n is large enough to receive the result. 


e Define the string as fixed-length. Name the string in a COMMON or 
MAP statement. 


Because the length of the returned string does not change, it is either 
padded with spaces or truncated. 


Using VAX BASIC in the Common Language Environment 21-9 


To pass an array to a VAX FORTRAN subprogram, you must specify 
BY REF. 


Note that VAX FORTRAN arrays are one-based, while VAX BASIC arrays 
are zero-based by default. For example, in VAX FORTRAN the array 
Two—D(5,3) represents a 5 by 3 matrix, while in VAX BASIC the array 
Two_d(5,3) represents a 6 by 4 matrix. You can adjust your array bounds 
in VAX BASIC by using the keyword TO when defining the array bounds. 
For more information on array bounds, see Chapter 8. 


When passing two-dimensional arrays as parameters, keep in mind that 
VAX FORTRAN addresses array elements in column major order, while 
VAX BASIC refers to array elements in row major order. That is, VAX 
FORTRAN arrays are of the form Fortran—array(column,row), while VAX 
BASIC array elements are addressed as Basic_array(row,column). The 
VAX FORTRAN array Grid(x,y) is therefore referred to as GRID(y,x) in 
VAX BASIC. You should reverse references to array elements when pass- 
ing arrays between VAX BASIC and VAX FORTRAN program modules. 
You can do this in one of two ways: 


¢ Reverse array bounds in parameter lists 


¢ Switch row and column variables within loops in your program 
module 


The following example shows a VAX BASIC program that passes a 
two-dimensional array to a VAX FORTRAN subprogram. 


Example 


VAX BASIC Main Program: 


PROGRAM call_fortran 
! The VAX BASIC main program prints the array before 
! calling the subroutine 
EXTERNAL SUB forsub (WORD DIM(,) BY REF) 
DIM WORD array_x(i TO 10, 1 TO 5) 
FOR column = 1 TO 5 
FOR row = 1 TO 10 
array_x(row,column)=(10*row + column) 
PRINT array_x(row,column) ; 
NEXT row 
PRINT 
NEXT column 
PRINT 


CALL forsub(array_x(,) BY REF) 


END PROGRAM 
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FORTRAN Subprogram: 


Cc The FORTRAN subprogram receives 
C and then prints the same array 


SUBROUTINE forsub(f_array) 
INTEGER*2 f_array (5,10) 
DO 20 row = 1,5 
TYPE *, (f_array(row,column), column = 1,10) 
20 CONTINUE 
RETURN 
END 


You can pass only the data types that VAX BASIC and VAX FORTRAN 
have in common. You cannot pass a complex number from a VAX 
FORTRAN program to a VAX BASIC program, because VAX BASIC 
does not support complex numbers. However, you can pass a complex 
number as two floating-point numbers and treat them independently in 
the VAX BASIC program. 


21.4 Calling System Routines 


The steps for calling system routines are the same as those for calling 
any external routine. However, when calling system routines, you need 
to provide additional information, which is discussed in the following 
sections. 


21.4.1 VAX/VMS Run-Time Library Routines 


The VAX/VMS Run-Time Library routines are grouped according to the 
types of tasks they perform. The routines in each group have a prefix that 
identifies them as members of a particular VAX/VMS Run-Time Library 
facility. Table 21-2 lists all the language-independent Run-Time Library 
facility prefixes and the types of tasks each facility performs. 


Using VAX BASIC in the Common Language Environment 21-11 


Table 21-2: 


Facility Prefix 
DTK$ 


LIB$ 


MTH$ 


OTSS$ 


PPL$ 


SMG$ 


STR$ 


Run-Time Library Facilities 


Types of Tasks Performed 


DECtalk routines that are used to control DIGITAL’s DECtalk 
device 


General purpose routines that obtain records from devices, 
manipulate strings, convert data types for I/O, allocate 
resources, obtain system information, signal exceptions, 
establish condition handlers, enable detection of hardware 
exceptions, and process cross-reference data 


Mathematics routines that perform arithmetic, algebraic, and 
trigonometric calculations 


Language-independent support routines that perform tasks 
such as data type conversions as part of a compiler’s gener- 
ated code 


Parallel processing routines that help you implement concur- 
rent programs on single-CPU and multiprocessor systems 


Screen management routines that are used in designing, 
composing, and keeping track of complex images on a video 
screen 


String manipulation routines that perform such tasks as 
searching for substrings, concatenating strings, and prefixing 
and appending strings 


21.4.2 System Service Routines 


System services are system routines that perform a variety of tasks such as 
controlling processes, communicating among processes, and coordinating 


1/O 


Unlike the VAX/VMS Run-Time Library routines, which are divided into 
groups by facility, all system services share the same facility prefix (SYS$). 
However, these services are logically divided into groups that perform 
similar tasks. Table 21-3 describes these groups. 
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Table 21-3: 
Group 

AST 

Change Mode 
Condition Handling 
Event Flag 


Information 


Input/Output 


Lock Management 
Logical Names 
Memory Management 
Process Control 


Security 


Time and Timing 


System Services 


Types of Tasks Performed 

Allows processes to control the handling of ASTs 
Changes the access mode of particular routines 
Designates condition handlers for special purposes 


Clears, sets, reads, and waits for event flags, and 
associates with event flag clusters 


Returns information about the system, queues, jobs, 
processes, locks, and devices 


Performs I/O directly, without going through VAX RMS 


Enables processes to coordinate access to shareable 
system resources 


Provides methods of accessing and maintaining pairs of 
character string logical names and equivalence names 


Increases or decreases available virtual memory, controls 
paging and swapping, and creates and accesses shareable 
files of code or data 


Creates, deletes, and controls execution of processes 
Enhances the security of VAX/VMS systems 


Schedules events, and obtains and formats binary time 
values 


21.4.3 System Routine Arguments 


All of the system routine arguments are described in terms of the following 


information: 
e VMS usage 
e Data type 


¢ Type of access allowed 


e Passing mechanism 
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VMS usages are data structures that are layered on the standard VMS/VMS 
data types. For example, the VMS usage mask_longword signifies an 
unsigned longword integer that is used as a bit mask, and the VMS 
usage floating_point represents any VAX/VMS floating-point data type. 
Table 21-4 lists all the VMS usages and the VAX BASIC statements you 
need to implement them. 


Table 21-4: VMS Usages 


VMS Usage VAX BASIC Implementation 
access_bit_names Not applicable (NA) 
access__mode BYTE (signed) 
address LONG 
address_range LONG address_range (1) 

or 


RECORD Address_range 
LONG beginning—address 
LONG ending—address 


END RECORD 
arg_list NA 
ast__procedure EXTERNAL LONG FUNCTION ast_proc ! 
boolean LONG 
byte_signed BYTE 
byte_unsigned BYTE 2 
channel WORD 
char_string STRING 
complex_number RECORD complex 


REAL real_part 
REAL imaginary—part 


END RECORD 
cond_value LONG 
context LONG 


lUse the LOC function to pass the address of an AST routine to a system service. Specify BY 
VALUE for the passing mechanism. 


? although unsigned data structures are not directly supported in VAX BASIC, you can substitute the 
signed equivalent provided you do not exceed the range of the signed data structure. 
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Table 21-4 (Cont.): 
VMS Usage 


date_time 
device_name 
ef_cluster_name 
ef_number 
exit_handler_block 


fab 
file_protection 


floating_point 


function_code 


identifier 


io_status_block 


VMS Usages 


VAX BASIC Implementation 


BASIC$QUADWORD ? 
STRING 

STRING 

LONG 


RECORD EHCB 
LONG flink 
LONG handler_addr 
BYTE arg_count 
BYTE FILL(3) 
LONG status_value_addr 
END RECORD 


NA 
LONG 


SINGLE 

DOUBLE 
GFLOAT 
HFLOAT 


RECORD function-code 
WORD major-function 
WORD subfunction 

END RECORD 


LONG 


RECORD iosb 
WORD iosb_field(1 to 4) 
END RECORD 


3 The definition of the RECORD structures are included in the VAX BASIC system definitions text 
library. See Section 21.4.4 for more information. 
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Table 21—4 (Cont.): 


VMS Usage 


item —list__2 


item —list_3 


item —list_pair 


VMS Usages 
VAX BASIC Implementation 


RECORD item_list_two 
GROUP item(15) 
VARIANT 
CASE 
WORD comp_length 
WORD code 
LONG comp_address 
CASE 
LONG terminator 
END VARIANT 
END GROUP 
END RECORD 


RECORD item _list_3 
GROUP item (15) 
VARIANT 
CASE 
WORD buf_len 
WORD code 
LONG buffer_address 
LONG length_address 
CASE 
LONG terminator 
END VARIANT 
END GROUP 
END RECORD 


RECORD item _list—pair 
GROUP item(15) 
VARIANT 
CASE 
LONG code 
LONG item—value 
CASE 
LONG terminator 
END VARIANT 
END GROUP 
END RECORD item_list—pair 
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Table 21—4 (Cont.): 
VMS Usage 


item —quota_list 


lock_id 
lock__status_block 
lock_value_block 
logical_name 
longword_signed 
longword_unsigned 
mask_byte 
mask_longword 
mask__quadword 
mask_word 


null_arg 


octaword_signed 
octaword_unsigned 
page_—protection 
procedure 
process_id 


process_name 


VMS Usages 


VAX BASIC Implementation 


RECORD item—quota_list 
GROUP quota(n) 
VARIANT 
CASE 
BYTE quota_name 
LONG item—value 
CASE 
BYTE list_end 
END VARIANT 
END GROUP 
END RECORD 


LONG 
NA 

NA 

STRING 

LONG 

LONG ? 

BYTE 

LONG 
BASIC$QUADWORD 2 
WORD 


A null argument is indicated by a comma 
used as a placekeeper in the argument list. 


BASIC$6OCTAWORD 
BASICSOCTAWORD 

LONG 

EXTERNAL LONG FUNCTION proc 
LONG 

STRING 





2 although unsigned data structures are not directly supported in VAX BASIC, you can substitute the 
signed equivalent provided you do not exceed the range of the signed data structure. 


3The definition of the RECORD structures are included in the VAX BASIC system definitions text 
library. See Section 21.4.4 for more information. 
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Table 21-4 (Cont.): VMS Usages 


VMS Usage 
quadword_signed 


quadword_unsigned 
rights_holder 

rights_id 

rab 

section _id 

section_name 

system _access_id 
time_name 

uic 

user_arg 

varying_arg 
vector_byte_signed 
vector_byte_unsigned 
vector_longword_signed 
vector_longword_unsigned 
vector_.quadword_signed 
vector_quadword_unsigned 
vector_word_signed 
vector_word_unsigned 
word_signed 


word_unsigned 


VAX BASIC Implementation 


BASIC$QUADWORD ? 
BASIC$QUADWORD ? 
BASIC$QUADWORD ? 
LONG 

NA 
BASIC$QUADWORD ° 
STRING 
BASIC$QUADWORD ? 
STRING 

LONG 

LONG 

Dependent upon application. 
BYTE array(n) 

BYTE array(n) 
LONG array(n) 

LONG array(n) . 

NA 

NA 

WORD array(n) 
WORD array(n) 2 
WORD 

WORD 2 


although unsigned data structures are not directly supported in VAX BASIC, you can substitute the 
signed equivalent provided you do not exceed the range of the signed data structure. 


3 


The definition of the RECORD structures are included in the VAX BASIC system definitions text 


library. See Section 21.4.4 for more information. 
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If a system routine argument is optional, it will be indicated in the format 
section of the routine description in one of two ways: 


[,optional-argument] 
,[optional-argument] 


If the comma appears outside the brackets, you must either pass a zero 
by value or use a comma in the argument list as a placeholder to indicate 
the place of the omitted argument. If this is the last argument in the list, 
you must still include the comma as a placeholder. If the comma appears 
inside the brackets, you can omit the argument altogether as long as it is 
the last argument in the list. 


21.4.4 Including Symbolic Definitions 


To enhance program development, VAX BASIC allows you to use sym- 
bolic definitions. Symbolic definitions are names or symbols associated 
with values. These symbols are used in many ways; the value associated 
with a symbol can be a status code, a mask, or an offset into a data struc- 
ture. Many system routines depend on values that are defined in separate 
symbol definition files. For example, the status code for successful com- 
pletion has a value of one. However, this code for successful completion 
is defined in the system library (STARLET) as the symbol SS$_NORMAL. 


A program might compare the status code returned by a system service to 
either the symbolic constant SS$_NORMAL or the integer value 1. The 
program would execute the same way in either case. In the first case, the 
value for SS$_NORMAL is supplied at link time by the VAX/VMS Linker. 
In the second case, the value one is included in the program as a literal 
constant. The advantages of using symbolic definitions are as follows: 


¢ Because symbolic definition names are mnemonic, the program is 
easier to read and understand. 

e It is easier to write the symbolic definition and let the VAX/VMS 
Linker fill in the value, than to look up the value associated with the 
symbol and include that value in the program. 

¢ Should the value associated with a symbol ever change, you must 
relink the program. To change a hard-coded definition, you must edit 
the source file, then recompile and relink. 


Symbolic definitions used by system services are located in the default 
system library, STARLET.OLB. 
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For Run-Time Library routines, the only time that you need to include 
symbolic definitions is when you are calling an SMG$ routine, or when 
you are calling a routine that is a jacket to a system service. (A jacket 
routine in the Run-Time Library is a routine that provides a simpler, more 
easily used interface to a system service.) If you call a routine in the 
SMG$ facility, you must include the definition file SMGDEF. All system 
services, however, require that you include SSDEF to check status. Many 
other system services require other symbol definitions as well. 


To determine whether or not you need to include other symbolic defini- 
tions for the system service you want to reference, refer to the documen- 
tation for that service. If the documentation states that values are defined 
in the specified macro, you must include those symbolic definitions in 
your program. VAX BASIC provides a text library that contains symbolic 
definitions that can be accessed using the %INCLUDE directive. In the 
following example, the definition file, SMGDEF is included from the text 
library SYS$LIBRARY:BASIC$STARLET.TLB: 


“INCLUDE "SMGDEF" %FROM %LIBRARY "SYS$LIBRARY : BASIC$STARLET.TLB" 


For more information on including text libraries, see Chapter 18. 


21.4.5 Condition Values 


Many system routines return a condition value that indicates success or 
failure. If a condition value is returned, you should check this value after 
you call a system routine and control returns to your program. 


Condition values indicating success always appear first in the list of 
condition values for a particular routine, and success codes always have 
odd values. A success code that is common to many system routines 

is the condition value SS$_NORMAL, which indicates that the routine 
completed normally and successfully. You can test for this condition value 
as follows: 


ret_status = SMG$CREATE_PASTEBOARD(pb_id) 
IF (ret_status <> SS$_NORMAL) THEN 

CALL LIB$STOP(ret_status BY VALUE) 
END IF 


Because all success codes have odd values, you can check a return status 
for any success code. For example, you can cause execution to continue 
only if a success code is returned by including the following statements in 
your program. 
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ret_status = SMG$CREATE_PASTEBOARD (pb_id) 
IF (ret_status AND 1%) = 0% THEN 

CALL LIB$STOP(ret_status BY VALUE) 
END IF 


In general, you can check for a particular success or failure code or you 
can test the condition value returned against all success codes or all failure 
codes. 


21.5 Examples of Calling System Routines 


This section provides complete examples of calling system routines from 
VAX BASIC. In addition to the examples provided here, the VAX/VMS 
Run-Time Library Routines Reference Manual and the VAX/VMS System 
Services Reference Manual also provide examples for selected routines. 
Refer to these manuals for help on the use of a specific system routine. 


The following example uses a function that invokes the SYS$TRNLNM 
system service. SYS$TRNLNM translates a logical name to an equivalence 
name. It places the equivalence name string into a string variable you 
supply in the parameter list. 


System services never change a string variable’s length. Therefore, if you 
use a syStem service that returns a string, be sure that the receiving string 
variable is long enough for the returned data. You can make sure of this 
in one of two ways: 


e Define the string variable’s length in a MAP, COMMON or RECORD 
definition. 

e Assign a long string to the variable (for example, A$ = SPACE$(80)). 
This pre-extends the variable so that it is long enough to receive all of 
the returned data. 


Example 


10 !This function attempts to translate a logical name while searching 
!through all of the tables defined in LNM$DCL_LOGICAL. If the translation 
!is successful, $TRNLNM returns the equivalence name string. 


FUNCTION STRING Translate(STRING Logical_name) 
EXTERNAL LONG FUNCTION SYS$TRNLNM (LONG, STRING, STRING, LONG, ITEM_LIST) 
EXTERNAL LONG CONSTANT LNM$M_CASE_BLIND, LNM$_STRING, SS$_NORMAL 


!Declare the parameters 


DECLARE LONG attributes, & 
trans_status 
DECLARE WORD equiv_len 
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!Declare the value returned by the function. 
DECLARE LONG CONSTANT Buffer_length = 255 


RECORD item_list 
GROUP item (1) 
VARIANT 
CASE 
WORD Buf_len 
WORD Code 
LONG Buffer_address 
LONG Length_address 
CASE 
LONG Terminator 
END VARIANT 
END GROUP item 
END RECORD item_list 


!Declare an instance of the record 
DECLARE ITEM_LIST TRNLNM_ITEMS 
!Define a common area for Translation_buffer 


COMMON (Trans_buffer) & 
STRING Translation_buffer = Buffer_length 


!Setting TRN$LNM to not distinguish between uppercase and lowercase 
!'letters in the logical name to be translated 


Attributes = LNM$M_CASE_BLIND 
!Assign values to each record item 


TRNLNM_ITEMS: :item(0)::Buf_len = Buffer_length 

TRNLNM_ITEMS: :item(0)::Code = LNM$_STRING 
TRNLNM_ITEMS: :item(0) : :Buffer_address = LOC(Translation_buffer) 
TRNLNM_ITEMS: : item(0)::Length_address = LOC(Equiv_len) 
TRNLNM_ITEMS: :item(1)::Terminator = 0% 


!Invoke the function 


TRANS_STATUS = SYS$TRNLNM(attributes,"LNM$DCL_LOGICAL", logical_name, & 
, trnlnm_items) 


'Check the condition value 


IF trans_status AND SS$_NORMAL 


THEN 
Translate = LEFT(Translation_buffer, Equiv_len) 
ELSE 
Translate = "" 
END IF 
END FUNCTION 


This next example is a complete program that demonstrates the use 
of the system service $QIOW. Unlike SYS$QIO, SYS$QIOW performs 
synchronously; SYS$QIOW returns a condition value to the caller after 
I/O operation is complete. 
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Example 


10 


!Declare SYS$QIOW as an EXTERNAL FUNCTION 


EXTERNAL LONG FUNCTION SYS$QIOW(,WORD BY VALUE,LONG BY VALUE,WORD DIM() & 
BY REF,,,STRING BY REF,LONG BY VALUE,, & 
LONG BY VALUE, ,) 

!Declare SYS$ASSIGN as an EXTERNAL FUNCTION 


EXTERNAL LONG FUNCTION SYS$ASSIGN(STRING,WORD, ,) 
EXTERNAL LONG CONSTANT IO0$_WRITEVBLK 
!'Declare the parameters 


DECLARE STRING my_term, out_str, & 
WORD term_chan, counter, stat_block(3) ,& 
LONG ret_status, msg_len, car_cntrl 


out_str = "Successful $QIOW output!" 
my_term = "SYS$COMMAND" 
msg_len = LEN(out_str) 

car_cntrl = 32% 


‘Assign a channel to the terminal 


ret_status = SYS$ASSIGN(my_term, term_chan, ,) 
CALL LIB$STOP(ret_status BY VALUE) IF (ret_status AND 1%) = 0% 


{Output the message four times 
FOR counter = 1% to 4% 


ret_status = SYS$QIOW(,term_chan BY VALUE, IO0$_WRITEVBLK BY VALUE, & 
stat_block() BY REF,, ,out_str BY REF, & 
msg_len BY VALUE, ,car_cntrl BY VALUE, ,) 
CALL LIB$STOP(ret_status BY VALUE) IF (ret_status AND 1%) = 0% 
CALL LIB$STOP(stat_block(0%) BY VALUE) & 
IF (stat_block(0%) and 1%) = 0% 
NEXT counter 


END 


Output 


Successful $QIOW output! 
Successful $QIOW output! 
Successful $QIOW output! 
Successful $QIOW output! 


In addition to invoking the function SYS$QIOW, the previous example 
also invokes the function SYS$ASSIGN. This function provides a process 
with an I/O channel so that input and output operations can be performed 


on a logical device name (my_term). As soon as SYS$ASSIGN is invoked 
and a path is established to the device, a counter is set up to invoke 

the $QIOW function four times. Once all I\O operations are complete, 
$QIOW returns to the caller. 
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21.6 The VAX Procedure Calling and Condition Handling Standard 


The primary purpose of the VAX Procedure Calling and Condition 
Handling Standard is to define the concepts for invoking routines and 
passing data between them. Some of the interface attributes that the 
VAX Procedure Calling and Condition Handling Standard specifies are as 
follows: 


e The argument list 

e The return of the function value 
e = Register usage 

e Stack usage 


These attributes are examined in more detail in the following sections. 
The VAX Procedure Calling and Condition Handling Standard also defines 
such interfaces as the calling sequence, the argument data types and 
descriptor formats, condition handling, and stack unwinding. These 
attributes are discussed in detail in the Introduction to VAX/VMS System 
Routines. 


21.6.1 The Argument List 


One of the module interfaces defined by the VAX Procedure Calling and 
Condition Handling Standard is the argument list. You use an argument 
list to pass information to a routine and receive results. An argument list 
is a collection of longwords in memory that represents a routine parameter 
list and possibly includes a function value. Figure 21-1 shows a typical 
argument list. 
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Figure 21-1: Structure of a VAX Argument List 





ZK-5503-86 


The VAX/VMS operating system requires that the first longword be 
present. This longword stores the number of arguments (the argument 
count: 1) as an unsigned integer value in the low byte of the longword. 
The remaining 24 bits of the first longword are reserved for DIGITAL use 
and should be zero. The longwords labeled arg] through argn are the 
actual parameters, which can be any of the following: 


e An uninterpreted 32-bit value (passed by value) 
e An address (passed by reference) 
e An address of a descriptor (passed by descriptor) 


The forms of the arguments in the argument list depend on the passing 
mechanisms specified. The argument list contains the parameters that are 
passed to the routine. If, for example, you pass three arguments, the first 
one by value, the second by reference, and the third by descriptor, the 
argument list would contain the value of the first argument, the address 
of the second, and the address of the descriptor of the third. Figure 21-2 
illustrates this argument list. 
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Figure 21-2: Example of a VAX Argument List 


copy of the first parameter 
address of the second parameter 
address of descriptor of the third parameter 


ZK-5504-86 















21.6.2 The Return of the Function Value 


A function is a routine that returns a single value to the calling routine. 
The function value represents the return value that is assigned to the func- 
tion’s identifier during execution. According to the VAX Procedure Calling © 
and Condition Handling Standard, a function value can be returned as 
either an actual value or a condition value that indicates success or failure. 


21.6.3 Register and Stack Usage 


The VAX Procedure Calling and Condition Handling Standard defines 


several registers. These registers and their defined uses are listed in 
Table 21-5. 
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Table 21-5: VAX Register Usage 


Register Use 

PC Program counter 

SP Stack pointer 

FP Current stack frame pointer 

AP Argument pointer 

R1 Environment value (when necessary) 
RO, R1 Function value return registers 


The called routine can use registers R2 through R11 for computation and 
the AP register as a temporary register. 


The stack is a Last-In/First-Out (LIFO) temporary storage area allocated by 
the system for each user process. On the call stack, the system maintains 
information about each routine call in the current image. Each time a 
routine is called by a program, the hardware creates a structure on the 
call stack known as the call frame. The call frame for each active routine 
contains the following: 


e A pointer to the call frame of the previous routine call. This pointer 
corresponds to the frame pointer (FP). 


e The argument pointer (AP) of the previous routine call. 


e The storage address of the point at which the routine was called; 
that is, the address of the instruction following the call to the current 
routine. This address is called the program counter (PC). 


e The contents of other general registers. Based on a mask specified 
in the control information, the system restores the saved contents of 
these registers to the calling routine when control returns to it. 


When execution of a routine ceases, the system uses the frame pointer in 
the call frame of the current routine to locate the frame of the previous 
routine. The system then removes the call frame of the current routine 
from the stack. 
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21.7 Additional Information 


The information provided on system routines in this chapter is general to 
all system services and VAX/VMS Run-Time Library routines. For specific 
information on these routines, refer to the VAX/VMS Run-Time Library 
Routines Reference Manual and the VAX/VMS System Services Reference 
Manual. 


For more information on the VAX Procedure Calling and Condition 
Handling Standard, see the Introduction to VAX/VMS System Routines. For 
information on programming considerations with external routines, refer 
to the Introduction to VAX/VMS System Routines and the Guide to Creating 
Modular Procedures on VAX/VMS. 


21-28 Using VAX BASIC in the Common Language Environment 


Chapter 22 


Libraries and Shareable Images 


Libraries and shareable images allow you to access program symbols and 
incorporate commonly used routines into your source code. This chapter 
describes how to create and access libraries and shareable images in 

VAX BASIC. 


22.1 Introduction 


Libraries are files that can contain object modules, text modules and 
shareable images. There are two types of libraries: system-supplied and 
user-supplied. System-supplied libraries are provided by the VAX/VMS 
system, whereas user-supplied libraries are libraries that you create. 


Shareable images are similar to libraries; they contain code that can be 
shared by other programs. However, shareable images contain executable 
code rather than object code. 


If you have routines that are used in many programs, placing the routines 
in object module libraries or shareable images lets you access them at link 
time. You do not need to include the routines in the source code, thus 
shortening compilation time and conserving disk space. 


If you have routines that are used simultaneously by many different 
programs, placing the routines in installed shareable images can improve 
performance at run time, conserve main physical memory, and reduce 
paging I/O because one copy of the executable code is shared by all users. 
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Object module libraries, shareable image libraries and shareable images 
can be accessed in the BASIC environment as well as at DCL command 
level. When you link programs at DCL command level, these libraries 
can contain object code created by any VAX native mode compiler or 
assembler. 


When you run a program in the BASIC environment, you can access: 


¢ Object libraries containing only VAX BASIC object code (object code 
from SUB, FUNCTION and PICTURE subprograms) 


e Sharable image libraries that contain BASIC or non-BASIC object code 
(such as a transfer vector written in VAX MACRO) 


Only BASIC subprograms can be loaded into the environment with the 
LOAD command. 


For a more thorough understanding of libraries and shareable images, refer 
to the VMS Linker Utility Manual and the Guide to Creating Modular Library 
Procedures. See the VMS Install Utility Manual for more information 

on installing shareable images. For information on text libraries, see 
Chapter 18 in this manual. 


22.2 System-Supplied Libraries 


If symbols are unresolved after the VAX/VMS Linker searches all user- 
supplied libraries, the linker goes on to search the files in the default 
system library. VAX/VMS supplies the following system libraries: 
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System Library 
IMAGELIB.OLB 


STARLET.OLB 


Purpose 


This library contains the symbol tables for the parts 
of the VAX Common Run-Time Library (RTL) that 
are in shareable images. If either the VAX/VMS 
Linker or the VAX BASIC compiler needs to search 
the default system library, it searches the shareable 
image symbol table library (IMAGELIB.OLB) first. 


This library is an object module library containing 
the object files used to create the shareable image 
version of the RTL, as well as other less frequently 
used procedures. This object library also contains 
modules for interfacing to VAX/VMS System 
Services. If program symbols remain unresolved af- 
ter the VAX/VMS Linker searches IMAGELIB.OLB, 
the linker then searches this library. 


The linker searches modules in the following order: 


1. Modules and libraries specified in the LINK command line, in the 


order given 


2. User-supplied libraries (logicals of the form LNK$LIBRARY and 
LNK$LIBRARY_1 through LNK$LIBRARY_999) 
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3. Images contained in IMAGELIB.OLB 
4. Modules contained in STARLET.OLB 


If the linker finds no needed routines in the RTL shareable images, it does 
not include any shareable images in the image being created. You can use 
the /NOSYSSHR qualifier to the LINK command to suppress the linker’s 
search of RTL shareable images. Similarly, you can use the /NOSYSLIB 
qualifier to suppress the linker’s search of both RTL shareable images and 
STARLET.OLB. 


Note that the VAX/VMS Linker searches user-supplied libraries before 
searching the default system library. This means that, if one of your 
modules has the same name (program symbol) as a VAX/VMS System 
Service or an RTL routine, the VAX/VMS Linker will include your module 
in the resulting image rather than the system service or RTL routine. 


22.3 Creating User-Supplied Object Module Libraries 


You create a user-supplied object module library with the DCL command 
LIBRARY. To do this, you must specify a library file specification as well 

as a list of the program modules you want to insert into the library. For 

example: 


$ BASIC MODULE1 , MODULE2 
$ LIBRARY/CREATE TESTLIB1.O0LB MODULE1 .OBJ,MODULE2 .OBJ 


The BASIC command creates object files from MODULE1.BAS and 
MODULE2.BAS. The LIBRARY command creates an object module library 
named TESTLIB1.OLB and inserts MODULE1.OBJ and MODULE2.OBJ 
into it. See the VAX/VMS DCL Dictionary for more information on the 
LIBRARY command. 


22.3.1 Accessing User-Supplied Object Module Libraries in the BASIC 
Environment 


Within the BASIC environment, VAX BASIC allows you to automatically 
access user-supplied object module libraries containing object files created 
by VAX BASIC. To do this, you must assign the logical name BASIC$LIBn 
to each library you wish to access, where n represents a number from 0 

to 9. For example: 


$ ASSIGN USER$$DEV: [SMITH] TESTLIB.OLB BASIC$LIBO 
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After you enter this command, a program executing in the BASIC envi- 
ronment automatically accesses USER$$DEV:[SMITH]TESTLIB.OLB to 
resolve program symbols. Note that this command assigns BASIC$LIBO 
as a process-wide logical name. A privileged user can also assign a VAX 
BASIC library as a group- or system-wide logical name. 


22.3.2 Accessing User-Supplied Object Module Libraries at DCL Level 


To access user-supplied object module libraries at DCL level, you must 
specify the /LIBRARY qualifier to the DCL command LINK. For example: 


$ LINK MAIN, TESTLIB/LIBRARY 


This command causes the linker to search TESTLIB.OLB if there are 
unresolved symbols in the VAX BASIC object module MAIN.OBJ. You 
can also explicitly include a module from a library with the /INCLUDE 
qualifier: 


$ LINK MAIN, TESTLIB/LIBRARY/INCLUDE = (modulei,module2) 


This command causes the VAX/VMS Linker to include module1 and 
module2 from TESTLIB.OLB, whether or not it needs these modules to 
resolve symbols. 


As in the BASIC environment, BASIC at DCL level allows you to access 
user-supplied object module libraries automatically. However, a program 
executing at DCL level does not automatically search libraries that are 
assigned to the logical name BASIC$LIBO. Instead, the linker searches 
libraries that are assigned to the logical name LNK$LIBRARY. If you have 
more than one library for the linker to search, you must number these 
libraries consecutively otherwise the linker does not search past the first 
missing logical name. The linker allows you to number libraries from 1 
through 999. 


For example: 


$ ASSIGN USERS$$DEV: [KELLY] TESTLIB.OLB LNK$LIBRARY 
$ ASSIGN USER$$DEV: [KELLY] TESTLIB1.0LB LNK$LIBRARY_1 
$ ASSIGN USER$$DEV: [KELLY] TESTLIB2.0LB LNK$LIBRARY_2 


After you issue these commands, a program executing at DCL 
level automatically accesses USER$$DEV:[KELLY]TESTLIB.OLB, 
USER$$DEV:[KELLY]TESTLIB1.OLB and USER$$DEV:[KELLY] 
TESTLIB2.OLB to resolve program symbols. 
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On MicroVAX/VMS systems, LNK$LIBRARY_1 is already used 

by the system; therefore, you should begin your assignments with 
LNK$LIBRARY_2 and number any additional libraries consecutively. 
On other VAX/VMS systems, number the first library as LNK$LIBRARY, 
the second as LNK$LIBRARY_1, the third as LNK$LIBRARY_2, 

and so on. 


22.4 Shareable Images 


Shareable images are not directly executable. They contain executable 
code that can be shared by other images and are intended to be included 
by the VAX/VMS Linker in other images. You can access shareable 
images both in the BASIC environment and at DCL level, as described in 
the next two sections. 


The benefits of using shareable images include 


¢ Conserving disk storage space 

¢ Conserving main physical memory 

e Reducing paging I/O 

e Allowing shared memory-resident data bases 


e Eliminating the need to relink programs that access a new version of a 
shared routine 


Note that some of these benefits can only be realized if the shareable 
image is installed with the VAX/VMS Install Utility (INSTALL). 


To create a shareable image, use the /SHAREABLE qualifier to the DCL 
command LINK. In addition, you must specify at least one object module. 
For example: 


$ LINK/SHAREABLE progi 


This command creates an image that can be linked to other programs. 
You cannot execute a shareable image with the DCL command RUN. 


When a program is linked with a shareable image, the required shareable 
image code is not included in the created executable image on disk. This 
code is included by the image activator at run time. Therefore, many 
programs can reside on disk and be bound with a particular shareable 
image, and only one physical copy of that shareable image file needs to 
exist on disk. 
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If a shareable image has been installed, you conserve physical memory 
and potentially reduce paging I/O. In this case, many processes can 
include the physical memory pages of an installed shareable image in their 
address space. This reduces the requirements for physical memory. 


Paging occurs when a process attempts to access a virtual address that is 
not in the process working set. When this page fault occurs, the page is 
either in a disk file, in which case paging I/O is required, or is already 
in physical memory. If a page fault occurs for a shared page, the shared 
page may already be resident in memory and in this case, no paging I/O 
is required. 


22.4.1 Accessing Shareable Images in the BASIC Environment 


Within the BASIC environment, you can access only shareable images 
contained in shareable image libraries when you issue the DCL command 
RUN. VAX BASIC always searches the system shareable image library, 
SYS$LIBRARY:IMAGELIB.OLB. To cause VAX BASIC to search an addi- 
tional shareable image library, you must first create the shareable image 
library and then assign it to the logical name BASIC$LIB. To create a 
shareable image library, you must use the /CREATE and /SHARE quali- 
fiers to the DCL command LIBRARY. You must also specify the name of 
the library as well as the names of the shareable images that you wish to 
insert. For example: 


$ LIBRARY/CREATE/SHARE library_name prog1 


Once you have created the library, you must assign it to the logical name 
BASIC$LIBn where n represents a number from 0 to 9. For example: 


$ ASSIGN DEV$$DISK: [BOB.LIBRARIES]library_name BASIC$LIBO 


After you issue this command, a program executing in the BASIC environ- 
ment automatically accesses library_name as a shareable image. 
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22.4.2 Accessing Shareable Images at DCL Level 


To access a shareable image at DCL level, you must follow these steps: 


1. Write and compile a program unit that is to be inserted into a share- 
able image. 


2. Create an options file required for the link operation. 


3. Link the program with the qualifier /SHAREABLE and specify the 
options file with the /OPTION qualifier. 


4. Write a main program that accesses the routine in the shareable image. 
5. Compile the main program and link it with the shareable image. 


The following example is an illustration of how to access a shareable 
image at DCL level using these five steps. 


Step 1: Write and compile a program unit that is to be inserted into a 
shareable image. 


!Program name - ADD.BAS 

FUNCTION REAL ADD (LONG A, LONG B) 
ADD = A+B 

FUNCTIONEND 


Step 2: Create an options file required for the link operation. 


!Program name - ADDSUB.OPT 
UNIVERSAL = ADD 


Step 3: Link the program with the qualifiers /SHAREABLE and 
/OPTION. 


$ LINK/SHAREABLE ADD, ADDSUB/OPTION 


Copy the shareable image to SYS$SHARE;, or assign a logical name to the 
full image file specification. 


Step 4: Write a main program that accesses the routine in the shareable 
image. 


!Program name - CALLADD.BAS 

EXTERNAL REAL FUNCTION ADD (LONG, LONG) 
DECLARE LONG X,Y 

X=i 

Y=2 

PRINT ADD(X,Y) 

END 
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Step 5: Compile the main program and link it with the shareable image. 
$ LINK CALLADD, ADDMAIN/OPTION 


In order to link CALLADD with the shareable image ADD, you must have 
a VAX/VMS Linker options file specifying that ADD is a shareable image: 


{Options file - ADDMAIN.OPT 
ADD/SHAREABLE 


Now you are ready to execute the program. When you do this, the 
image activator attempts to locate the shareable image in the directory 
SYS$SHARE:. If you want the image activator to access a shareable image 
outside SYS$SHARE:, you must assign a logical name to the shareable 
image before you execute the program. That is, you must assign the full 
file specification of the shareable image to the name of the shareable 
image, as follows: 


$ DEFINE MYSHR DISK$WORKDISK: [MYDIR] MYSHR 


This is a very simple example of using shareable images. For a thorough 
understanding of shareable images, see the VAX/VMS Linker Reference 
Manual. 
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Chapter 23 


Extracting Record Definitions from the 
VAX Common Data Dictionary 


This chapter describes how to extract record definitions from the 
VAX Common Data Dictionary (CDD). 


23.1 Introduction to the CDD 


The VAX Common Data Dictionary (CDD) is a tool that supports sharing 
of data definitions by VAX/VMS programming languages and VAX 
Information Architecture products. Each language or product translates 
the generic definitions stored in the CDD into language- or product- 
specific definitions that it can use. Because CDD data definitions can be 
used by several different products, programmers do not have to write 
special programs to allow different products to work together or store 
redundant copies of data files. Also, because CDD data definitions are 
centrally located, you can change several programs by modifying a single 
data definition. 


There are two types of dictionaries: DMU-format and CDO-format. DMU- 
format dictionaries are the only type used prior to CDD/Plus Version 4.0. 
CDO-format dictionaries are introduced in CDD/Plus Version 4.0; they 
have the capability of recording dependency information, as described in 
Chapter 24. The two types of dictionaries can coexist on a system. 


Refer to Chapter 24 and the CDD/Plus documention for more information 
on CDD/Plus. 
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23.2 Extracting CDD Data Definitions in VAX BASIC 


A data definition is one type of CDD object. In VAX BASIC, you can 
extract only data definition objects into your program. 


To extract a CDD data definition in VAX BASIC, specify the %INCLUDE 
%FROM %CDD compiler directive and a CDD path name. You can use 

this to extract a data definition from either a DMU-format or CDO-format 
dictionary. For example: 


%INCLUDE %FROM %CDD "CDD$TOP.BASIC.BASICDEF" 


The %INCLUDE %FROM %CDD directive extracts the CDD data def- 
inition you specify, and translates it into VAX BASIC syntax. In VAX 
BASIC, the syntax for data definitions or data structures is defined by the 
RECORD statement. 


Once a CDD data definition is translated into RECORD statement syntax, 
you can reference the name of the RECORD statement in your VAX 
BASIC programs. After compilation, the translated RECORD statement is 
included as a part of your program’s listing. 


The following is an example of a CDD data definition and the translated 
VAX BASIC RECORD statement. In general, the examples in this chapter 
are of DMU-format CDD data definitions that were written in the VAX 
Common Data Definition Language (CDDL). Chapter 24 contains ad- 
ditional information about using the CDO utility to create CDO-format 
definitions for use with CDD/Plus. In all examples, the CDDL 

data definition is displayed in lowercase letters and the translated 
RECORD statement is displayed in uppercase letters. 


CDDL Definition 


define record cdd$top.basic.basicdef 
description is 


/* This is an example record containing 
only data types supported by VAX BASIC */. 
employee structure. 


street ' datatype is text 

size is 30 characters. 
city datatype is text 

size is 30 characters. 
state datatype is text 


size is 2 characters. 


23-2 Extracting Record Definitions from the VAX Common Data Dictionary July 198! 


zip_code structure. 


new datatype is packed decimal 
size is 4 digits. 
old datatype is packed decimal 


size is 5 digits. 
end zip_code structure. 


emp_number datatype is Sigiel word. 
wage_class datatype is text 

size is 2 characters. 
salary_ytd datatype is d_floating. 


end employee structure. 
end basicdef. 


Translated RECORD Statement 


1 “INCLUDE %FROM %CDD "CDD$TOP.BASIC.BASICDEF" 
C1 ! This is an example record containing 
C1 ! only data types supported by se BASIC 
C1 RECORD EMPLOYEE ! UNSPECIFIED 
Ci STRING STREET = 30 ! TEXT 
Ci STRING CITY = 30 ! TEXT 
C1 STRING STATE = 2 ! TEXT 
Ci GROUP ZIP_CODE ! UNSPECIFIED 
C1 DECIMAL(4 ,O ) NEW ! PACKED DECIMAL 
C1 DECIMAL(5 ,O ) OLD ! PACKED DECIMAL 
C1 END GROUP 
Ci WORD EMP_NUMBER ! SIGNED WORD 
C1 STRING WAGE_CLASS = 2 1 TEXT 
Ci DOUBLE SALARY_YTD ! D_FLOATING 
C1 END RECORD 


When VAX BASIC translates a CDD data definition, it does the following: 


e For DMU-format definitions, it takes the field name specified in the 
first CDDL STRUCTURE statement and assigns that name to the VAX 
BASIC RECORD. For CDO-format definitions, it takes the record name 
from the CDO DEFINE RECORD statement and assigns that name to 
the VAX BASIC record. In the preceding example, for instance, the 
first CDDL structure statement is employee structure. When VAX 
BASIC translates this line of the CDD data definition, it names the 
RECORD EMPLOYEE. If this first structure is unnamed, VAX BASIC 
signals the error “Record from CDD does not have a record name”. 


e Translates the field name in any subsequent CDDL STRUCTURE 
statement to be the name of a group. For instance, in the preceding 
example, the second STRUCTURE statement, zip_code structure, is 
translated to GROUP ZIP_CODE. 
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e¢ Translates subordinate field names in CDDL STRUCTURE statements 
to elementary components in the RECORD statement. In the pre- 
ceding example, for instance, the subordinate field name street is 
translated to STRING STREET. 


If you specify the /LIST qualifier, when VAX BASIC translates a CDD 
data definition, it does the following: 


e Begins each line of the RECORD statement with the letter “C” fol- 
lowed by a number. The “C’” tells you that the RECORD statement 
was translated from a CDD data definition. The number tells you the 
nesting level of the %INCLUDE %FROM %CDD directive within the 
source program. For example, if your source program directly extracts 
a CDD record definition, then each line is preceded by a “C1”. If the 
CDD extraction came from a file included in the source program, then 
each line of the record definition is preceded by a “C2”, and so on. 


e Includes the explanatory text in the CDDL DESCRIPTION clause as 
comment fields. 


e Translates the data type text in the subordinate field to a comment 
field that tells you the data type of each elementary RECORD com- 
ponent. For example, the comment ! TEXT tells you that STRING 
STREET is a text data type. 


VAX BASIC requires that a CDD data definition include a minimum of 
one structure to be translated into a RECORD statement. If a CDD data 
definition contains only a single subordinate field (without a structure), 
VAX BASIC signals an error message because it cannot give a name to the 
RECORD statement. For this reason, you cannot include a CDO FIELD 
definition in a VAX BASIC program. You can, however, include CDO 
RECORD definitions that contain that field. See Chapter 24 for more 
information. 


For more information on how VAX BASIC translates CDD data types, see 
Section 23.8. 
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23.3 CDD Path Names 


When you extract a CDD record definition with the VAX BASIC 
%INCLUDE %FROM %CDD directive, you specify a path name. The 
path name tells CDD where to locate a particular data definition in its 
directory. A CDD path name consists of a string of names separated by 
periods and enclosed in quotation marks. 


The origin is the top, or root, of a dictionary directory. This directory 
contains other dictionary directories and objects. For example: 


“INCLUDE %FROM %CDD "CDD$TOP .BASIC.EMPLOYEE_DATA" 


In this example, the path name CDD$TOP.BASIC.EMPLOYEE_DATA 
points to the root dictionary directory, CDD$TOP, which contains the dic- 
tionary directory BASIC, which in turn contains the object EMPLOYEE_— 
DATA. EMPLOYEE_DATA is a data definition. 


VAX BASIC allows three types of valid path name parameters when 
referring to CDD dictionary definitions. They differ in the method of 
specifying the dictionary origin. 


¢ Dictionary anchor path name 


An anchor path name begins with an anchor, which is a VMS 
directory specification, as the dictionary origin. The anchor spec- 
ifies the VMS directory that contains the CDO dictionary. This is 
known as the CDO naming convention. In the following example, 
MYNODE::DISK$2:[MYDIRECTORY] is the anchor: 


MYNODE: : DISK$2: [MYDIRECTORY] PERSONNEL . EMPLOYEES_REC 
¢ CDDS$TOP path name 


You use this to refer to either DMU-format dictionary definitions or 
CDO-format dictionary definitions in a compatibility dictionary. The 
path origin is always CDD$TOP. This is known as the DMU naming 
convention. For example: 


CDD$TOP . PERSONNEL . EMPLOYEES_REC 
e Relative path name 


You can omit the origin of a path name and specify a relative path 
name. To do this, you must first assign the name of a dictionary 
directory to the logical name CDD$DEFAULT. For example: 


$ DEFINE CDD$DEFAULT CDD$TOP.BASIC 
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Using this command defines the dictionary directory CDD$TOP.BASIC 
as the default start of your directory. You can override the defined 
default by specifying either CDD$TOP or an anchor in a path name 
(thereby specifying a full path name as described previously). 


Any path name that does not begin with either CDD$TOP or an 
anchor is automatically appended to the current CDD$DEFAULT. For 
example, you can specify: 


PERSONNEL. EMPLOYEES_REC 


If CDD$DEFAULT is MYNODE::MY$DISK:[MYDIR], the relative path 
name is the same as: 


MYNODE: :MY$DISK: [MYDIR] PERSONNEL. EMPLOYEES_REC. 


Similarly, if CDDS$DEFAULT is CDD$TOP.MYDIR, the relative path 
name is the same as: 


CDD$TOP .MYDIR.PERSONNEL . EMPLOYEES_REC. 


23.4 Specifying a CDD History List Entry 


When you extract a record from the CDD, you have the option of entering 
a history list entry in the CDD data base. The history list entry provides a 
history of users that access the CDD. 


You enter a history list entry by specifying either the DCL command 
BASIC/AUDIT or the BASIC environment command SET/AUDIT or 
COM/AUDIT. For example: 


$ BASIC/LIST/SHOW=CDD/AUDIT="Copied for Yearly Employee Analysis" 


Note that instead of typing the text directly on the command line, you can 
also specify a file specification that contains the history entry. 


When you specify a history list entry with AUDIT, the following informa- 
tion is included in the history log: 


e Your user name, UIC, and process name 
e The entry text you specify 
e That the access was by way of a VAX BASIC program 
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e That the access was an extraction (marked in the history log as 
COMPILE) 


¢ The name of the program module that requested the extraction and 
the time and date of the request 


A history list entry is included even if errors are signaled during compi- 
lation. Therefore, you should debug your program before you specify a 
history list entry. The default is /NOAUDIT. 


23.5 The NAME FOR BASIC Clause 


VAX BASIC supports the CDDL field attribute clause NAME FOR BASIC. 


The CDDL field attribute clause NAME FOR BASIC declares a facility- 
specific name for a field. For example: 


name for basic is "subject_name$" 


When you assign a name using the NAME FOR BASIC clause in a CDDL 
data definition, VAX BASIC recognizes only this name when you refer 

to the field. Note that when you use the NAME FOR BASIC clause, you 
can place dollar sign ($) and percent sign (%) suffixes in your RECORD 
statement field names. 


The following example is a CDDL data definition containing the NAME 
FOR BASIC clause, and the corresponding VAX BASIC RECORD 
statement. 


CDDL Definition 


define record city_study 
description is 


/* This example formats data resulting from a 
study on the relationship between place of birth 
and earning potential */. 

info structure. 


subject_name datatype text size 10 

name for basic is "subject_name$". 
birth_city datatype text size 10 

name for basic is "city_of_birth$". 
salary datatype signed byte 


name for basic is "salary%". 
end info structure. 
end city_study. 
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Translated RECORD Statement 


1 %INCLUDE %4FROM %CDD "CDD$TOP.BASIC.CITY_STUDY" 
C1 ! This example formats data resulting from a 
Ci ! study on the relationship between place of birt 
Ci ! and earning potential 
C1 RECORD INFO ! UNSPECIFIED 
C1 STRING SUBJECT_NAME$ = 10 ! TEXT 
C1 STRING CITY_OF_BIRTH$ = 10 ! TEXT 
C1 BYTE SALARY% ! SIGNED BYTE 


C1 END RECORD 


Be careful when you use the NAME FOR BASIC clause because it enables 
you to assign completely different names to the same field. 


For more information about the CDDL NAME FOR BASIC field attribute 
clause, see the CDD documentation. 


23.6 CDD Arrays 


The CDD supports three types of arrays: 


¢ Multidimensional arrays (the ARRAY clause) 


¢ One-dimensional, fixed length arrays (the OCCURS clause or ARRAY 
clause) 


e One-dimensional, variable length arrays (the OCCURS DEPENDING 
ON clause—note that VAX BASIC does not support this clause) 


Arrays are valid for any CDD field. VAX BASIC does not support dimen- 
sions on a RECORD statement. You cannot, therefore, declare an entire 
RECORD statement as an array. However, you can dimension an instance 
of the record. 


The following is an example of a CDD data definition containing arrays 
and the corresponding VAX BASIC RECORD statement. 


CDDL Definition 


define record cdd$top.basic.array1 
description is 


/* test arrays */. 
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array_1 structure. 


my_byte array 0:2 datatype Signed byte. 
my_string array 0:10 datatype text size 10. 
my_s_real array 0:2 0:4 datatype f_floating. 
my_d_real array 1:3 datatype d_floating. 
my_g_real occurs 4 times datatype g_floating. 
my_h_real occurs 4 times datatype h_floating. 
end array_1 structure. 
end arrayl. 


Translated RECORD Statement 


1 “INCLUDE %FROM %.CDD "CDD$TOP.BASIC.ARRAY1" 
C1 ! test arrays 
Ci RECORD ARRAY_1 ! UNSPECIFIED 
C1 BYTE MY_BYTE(O TO 2) ! SIGNED BYTE 
C1 STRING MY_STRING(O TO 10) = 10 ! TEXT 
C1 SINGLE MY_S_REAL(O TO 2,0 TO 4) ! F_FLOATING 
C1 DOUBLE MY_D_REAL(1 TO 3) ! D_FLOATING 
Ci GFLOAT MY_G_REAL(1 TO 4) ! G_FLOATING 
Ci HFLOAT MY_H_REAL(1 TO 4) ! H_FLOATING 
C1 END RECORD 


By default, arrays in the CDD are row-major. This means that when 
storage is allocated for the array, the rightmost subscript varies fastest. All 
VAX BASIC arrays are row-major. VAX BASIC does not support column- 
major arrays. If a CDD definition containing a column-major array is 
extracted, VAX BASIC signals the error “ <array-name> from CDD isa 
column major array”. 


By default, VAX BASIC extracts an array field from the CDD with the 
bounds specified in the data definition. However, if you use the qualifier 
/OLD_VERSION=CDD_ARRAYS when you extract a data definition, 
VAX BASIC translates the data definition with lower bounds as zero and 
adjusts the upper bounds. This means that an array with dimensions of 
(2,5) in the CDD is translated by VAX BASIC to be an array with a lower 
bound of 0 and an upper bound of 3. VAX BASIC issues an informational 
message to confirm the array bounds when you use this qualifier. 


The following CDD data definition and corresponding RECORD statement 
were extracted with the /OLD_.VERSION=CDD_ARRAYS qualifier. 
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CDDL Definition 


define record cdd$top.basic.array2 


description is 


/* test arrays with /old_version=cdd_arrays qualifier */. 


array_2 structure. 


signed byte. 
text size 10. 
f_floating. 
d_floating. 
gfloating. 
signed longword. 


h_floating. 


UNSPECIFIED 
SIGNED BYTE 
TEXT 

F_FLOATING 
D_FLOATING 
G_FLOATING 
SIGNED LONGWORD 
H_FLOATING 


my_byte array 0:2 datatype 
ny_string array 0:10 datatype 
my_s_real array 0:2 0:4 datatype 
my_d_real array 1:3 datatype 
mny_g_real occurs 4 times datatype 
dep_item datatype 
my_h_real occurs 4 times 
datatype 
end array_2 structure. 
end array2. 
Translated RECORD Statement 

1 “INCLUDE %FROM %CDD "CDD$TOP.BASIC. ARRAY2" 
C1 ! test arrays with /old_version=cdd_arrays qualifier 
C1 RECORD ARRAY_2 
C1 BYTE MY_BYTE(O TO 2) 
Ci STRING MY_STRING(O TO 10) = 10 
C1 SINGLE MY_S_REAL(O TO 2,0 TO 4) 
Ci DOUBLE MY_D_REAL(O TO 2) 
C1 GFLOAT MY_G_REAL(O TO 3) 
C1 LONG DEP_ITEM 
Ci HFLOAT MY_H_REAL(O TO 3) 
Ci END RECORD 


23.7 CDD Variants 


A variant comprises two or more fields of a record that provide alternative 
descriptions for the same portion of a record. 


The following is an example of a CDD data definition containing variant 
fields and the corresponding VAX BASIC RECORD statement. 
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CDDL Definition 


define record cdd$top.basic.variant_example 


description is 


/* test simple variant */. 


variant_example structure. 
ny_string datatype text size 9. 


variants. 
variant. 
my_s_real datatype f_floating. 
my_d_real datatype d_floating. 
end variant. 
variant. 
my_g_real datatype g_floating. 
my_h_real datatype h_floating. 
end variant. 
end variants. 
ny_byte datatype signed byte. 
end variant_example structure. 
end variant_example. 
Translated RECORD Statement 
1 %INCLUDE %FROM %.CDD "CDD$TOP.BASIC.VARIANT_EXAMPLE" 
C1 ! test simple variant 
C1 RECORD VARIANT_EXAMPLE ! UNSPECIFIED 
C1 STRING MY_STRING = 9 ! TEXT 
C1 VARIANT 
C1 CASE 
Ci SINGLE MY_S_REAL ! F_FLOATING 
Ci DOUBLE MY_D_REAL ! D_FLOATING 
Ci CASE 
Ci GFLOAT MY_G_REAL ! G_FLOATING 
Ci HFLOAT MY_H_REAL ! H_FLOATING 
Ci END VARIANT 
C1 BYTE MY_BYTE ! SIGNED BYTE 
Ci END RECORD 


CDD data definitions sometimes contain VARIANTS OF field description 
statements as well as simple variants. A CDD VARIANTS OF state- 
ment names a tag variable whose value at run time determines which 
of the variant fields is the current variant. VAX BASIC does not support 
the VARIANTS OF statement. If a CDD data definition containing a 
VARIANTS OF statement is extracted, VAX BASIC signals the informa- 
tional message, “%BASIC-I-CDDTAGIGN, <number> tag value from 
CDD ignored” and treats the VARIANTS OF as an ordinary variant and 


ignores the tag value. 
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23.8 CDD Data Types 


VAX BASIC supports only a subset of CDD data types. They are described 
in Table 23-1. 


Table 23-1: Supported CDD Data Types 


CDD Data Type VAX BASIC Translation 
TEXT STRING 

SIGNED BYTE BYTE 

SIGNED WORD WORD 

SIGNED LONGWORD LONG 

F_FLOATING SINGLE 

D_FLOATING DOUBLE 

G_FLOATING GFLOAT 

H_FLOATING HFLOAT 

PACKED DECIMAL DECIMAL 


If a CDD data definition containing an unsupported data type is extracted, 
VAX BASIC signals the informational message “CDDSUBGRO, datatype 
in CDD not supported, substituted group for: <field-name> ” and 
translates the data type by creating a group to contain the data type field. 
The group name is the name of the unsupported data type followed by 
the text “_VALUE”. This allows you to access the field name within the 


group. 
An example of how VAX BASIC translates unsupported CDD data types 


is shown in the following CDD data definition and corresponding VAX 
BASIC RECORD statement. 


CDDL Definition 


define record cdd$top.basic.stock 
description is 


/* this is an example data definition that contains 
data types not supported by VAX BASIC */. 


stock structure. 
product_no datatype is text 
size is 8 characters. 
date_ordered datatype is date. 
status_code datatype is unsigned byte. 
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quantity 


location 


unit_price 


datatype is unsigned longword 
aligned on longword. 

array 1:4 

datatype is text 

size is 30 characters. 
datatype is longword. 


end stock structure. 


end stock. 


Translated RECORD 
1 


Statement 


“%INCLUDE %FROM %.CDD "CDD$TOP .BASIC .STOCK" 


C1 ! This is an example data definition that contains 
C1 ! data types not supported by VAX BASIC 
Ci RECORD STOCK ! UNSPECIFIED 
Ci STRING PRODUCT_NO = 8 ! TEXT 
Ci GROUP DATE_ORDERED ! DATE 
Ci STRING STRING_VALUE = 8 
ci END GROUP 
Ci GROUP STATUS_CODE ! UNSIGNED BYTE 
Ci BYTE BYTE_VALUE 
Ci END GROUP 
C1 STRING FILL = 3 
Ci GROUP QUANTITY ! UNSIGNED LONGWORD 
Ci LONG LONG_VALUE 
ci END GROUP 
Ci STRING LOCATION(1 TO 4) = 30 ! TEXT 
Ci GROUP UNIT_PRICE ! UNSIGNED LONGWORD 
ci LONG LONG_VALUE 
Ci END GROUP 
Ci END RECORD 
“BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: STOCK: : DATE_ORDERED. 
YBASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: STOCK: :STATUS_CODE. 
“BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: STOCK: :QUANTITY. 
“%BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: STOCK: :UNIT_PRICE. 


Table 23-2 describes the CDD data types not supported by VAX BASIC 


and their translation. 
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Table 23-2: Unsupported CDD Data Types 


CDD Data Type 
UNSIGNED BYTE 


UNSIGNED WORD 


UNSIGNED LONGWORD 


SIGNED QUADWORD 


UNSIGNED QUADWORD 


SIGNED OCTAWORD 


UNSIGNED OCTAWORD 


F_FLOATING COMPLEX 


D_FLOATING COMPLEX 


G_FLOATING COMPLEX 


VAX BASIC Translation 


GROUP cdd-field-name 
BYTE BYTE_VALUE 
END GROUP 


GROUP cdd-field-name 
WORD WORD_VALUE 
END GROUP 


GROUP cdd-field-name 
LONG LONG__VALUE 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = 8 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = 8 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = 16 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = 16 
END GROUP 


GROUP cdd-field-name 
SINGLE SINGLE_R_VALUE 
SINGLE SINGLE_I_VALUE 
END GROUP 


GROUP cdd-field-name 
DOUBLE DOUBLE_R—VALUE 
DOUBLE DOUBLE_I_VALUE 
END GROUP 


GROUP cdd-field-name 
GFLOAT GFLOAT_R—VALUE 
GFLOAT GFLOAT_I_VALUE 
END GROUP 
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Table 23-2 (Cont.): Unsupported CDD Data Types 


CDD Data Type 
H_FLOATING COMPLEX 


ZONED NUMERIC 


UNSIGNED NUMERIC 


LEFT SEPARATE NUMERIC 


LEFT OVERPUNCHED 


NUMERIC 


RIGHT SEPARATE NUMERIC 


RIGHT OVERPUNCHED 


NUMERIC 


VARYING STRING 


BIT! 


DATE 


VAX BASIC Translation 


GROUP cdd-field-name 
HFLOAT HFLOAT_R—VALUE 
HFLOAT HFLOAT_I_VALUE 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = length 
END GROUP 


GROUP cdd-field-name 
STRING STRING_—VALUE = length 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = length + 1 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = length 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = length + 1 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = length 
END GROUP 


GROUP cdd-field-name 

WORD WORD_VALUE 

STRING STRING_VALUE = length 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = length /8 
END GROUP 


GROUP cdd-field-name 
STRING STRING_VALUE = 8 
END GROUP 





‘opp specifies bit field length in bits; VAX BASIC specifies string length in bytes. If the length in bits does not divide 
evenly into bytes, VAX BASIC signals the error “%BASIC-E-CDDBITFLD, field <fieldname> from CDD has bit offset or 


length. 
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Table 23-2 (Cont.): Unsupported CDD Data Types 


CDD Data Type VAX BASIC Translation 
POINTER GROUP cdd-field-name 
LONG LONG_VALUE 
END GROUP 
UNSPECIFIED GROUP cdd-field-name 
STRING STRING_VALUE = length 
END GROUP 
VIRTUAL FIELD Ignored 


The following sections describe how VAX BASIC translates CDD data 
types in greater detail. 


23.8.1 Character String Data Types 


There are two CDD character string data types, TEXT and VARYING 
STRING. The TEXT data type translates directly into the VAX BASIC 
STRING data type. VARYING STRING is not a supported VAX BASIC 
data type; therefore, VAX BASIC creates a group to contain the field. 


The following example is a CDDL definition that contains both the 
TEXT and VARYING STRING data types and the translated VAX BASIC 
RECORD statement. 


CDDL Definition 


define record cdd$top. basic. strings 
description is 


/* test */. 


basicstrings structure. 
abe datatype is text size is 10. 
xyz datatype is varying string size is 16. 
end basicstrings structure. 
end strings. 
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Translated RECORD Statement 


1 “INCLUDE %FROM %.CDD "CDD$TOP.BASIC.STRINGS" 
C1 ! test 
Ci RECORD BASICSTRINGS ! UNSPECIFIED 
C1 STRING ABC = 10 ! TEXT 
C1 GROUP XYZ ! VARYING STRING 
Ci WORD WORD_VALUE 
Ci STRING STRING_VALUE = 16 
C1 END GROUP 
C1 END RECORD 
6 Seine aaeure Es 1 
“BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 


substituted group for: BASICSTRINGS: :XYZ. 


In the VARYING STRING data type, the actual character string is preceded 
by a 16-bit count field. Therefore, VAX BASIC creates a WORD variable 
to hold the specified string length. 


NOTE 


The count field preceding the VARYING STRING is actually an 
UNSIGNED WORD. Therefore, the count field of a VARYING 
STRING whose length is greater than 32767 is interpreted by 
VAX BASIC as a negative number. 


In the preceding example, the group name (XYZ) is the same name as 
the CDD field. Therefore, VAX BASIC supplies an additional name for 
the RECORD components. The supplied names are WORD_VALUE and 
STRING_VALUE. For example, the following program statement creates 
an instance of the record BASICSTRINGS, called MY_REC: 


100 MAP (TEST) BASICSTRINGS MY_REC 


The names you use to reference these components in VAX BASIC are 
MY_REC::XYZ::WORD_VALUE and MY_REC::XYZ::STRING_VALUE. 
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23.8.2 


Integer Data Types 


The CDD refers to integer data types as fixed-point data types. The CDD 
supports BYTE, WORD, LONGWORD, QUADWORD, and OCTAWORD 
integer data types. Each of these data types can have the following 
additional attributes: 


e SIGNED 

e UNSIGNED 
e §=6SIZE 

e DIGITS 

e FRACTION 
e BASE 

e SCALE 


In CDDL, if integer data types are not specified as being signed or un- 
signed, the default is unsigned. VAX BASIC supports only signed BYTE, 
signed WORD, and signed LONGWORD integers. If a CDDL data defi- 
nition containing an unsigned BYTE, WORD, or LONGWORD integer is 
extracted, VAX BASIC signals the informational message “CDDSUBGRO, 
datatype in CDD not supported, substituted group for: <field-name> ”, 
and creates a group to contain the field. Because the group name is the 
same as the CDD field name, VAX BASIC assigns a new name to the field. 
This is shown in the following CDD data definition and corresponding 
VAX BASIC RECORD statement. 


CDDL Definition 


define record cdd$top. basic. integers 
description is 


/*Test of selected integer data types*/. 


basicint structure. 


ny_byte datatype is signed byte. 
my_ubyte datatype is byte. 

ny_word datatype is signed word. 

my _uword datatype is unsigned word. 
my_long datatype is signed longword. 
my_ulong datatype is unsigned longword. 


end basicint structure. 
end integers. 
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Translated RECORD Statement 


1 “INCLUDE %FROM %CDD "CDD$TOP.BASIC. INTEGERS" 
C1 ! Test of selected integer data types 
C1 RECORD BASICINT ! UNSPECIFIED 
C1 BYTE MY_BYTE ! SIGNED BYTE 
C1 GROUP MY_UBYTE ! UNSIGNED BYTE 
C1 BYTE BYTE_VALUE 
C1 END GROUP 
Ci WORD MY_WORD ! SIGNED WORD 
C1 GROUP MY_UWORD ! UNSIGNED WORD 
C1 WORD WORD_VALUE 
C1 END GROUP 
C1 LONG MY_LONG ! SIGNED LONGWORD 
C1 GROUP MY_ULONG ! UNSIGNED LONGWORD 
Ci LONG LONG_VALUE 
ci END GROUP 
Ci END RECORD 
seekeecuakua pha laches 1 
%BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 
substituted group for: BASICINT: :MY_UBYTE. 
“%BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 
substituted group for: BASICINT: :MY_UWORD. 
“BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 


substituted group for: BASICINT: :MY_ULONG. 


When the preceding data definition is extracted from the CDD, VAX 
BASIC signals an informational message for each of the unsigned data 
types, and names the CDD unsigned byte field BYTE_VALUE, the CDD 
unsigned word field WORD_VALUE, and the CDD unsigned longword 
field LONG_VALUE. 


VAX BASIC does not support QUADWORD or OCTAWORD integers. If 
a CDD definition contains a QUADWORD or OCTAWORD integer, VAX 
BASIC signals the informational message “CDDSUBGRO, datatype in 
CDD not supported, substituted group for: <field-name> ” and creates a 
group to contain the field and a string component within the group. The 
string component is 8 bytes for QUADWORD integers and 16 bytes for 
OCTAWORD integers. For example: 
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CDDL Definition 


define record cdd$top. basic. bigintegers 
description is 


/*Test of quadword and octaword integer data types*/. 


basicint structure. 
my_quad datatype is signed quadword. 
my_octa datatype is signed octaword. 
end basicint structure. 
end bigintegers. 


Translated RECORD Statement 


1 %INCLUDE %FROM %CDD "CDD$TOP.BASIC.BIGINTEGERS" 

C1 ! Test of quadword and octaword integer data types 

Ci RECORD BASICINT ! UNSPECIFIED 

Ci GROUP MY_QUAD ! SIGNED QUADWORD 

Ci STRING STRING_VALUE = 8 

Ci END GROUP 

C1 GROUP MY_OCTA ! SIGNED OCTAWORD 

Ci STRING STRING_VALUE = 16 

ci END GROUP 

Ci END RECORD 
“%BASIC-I-CDDSUBGRO, data type in CDD not supported, 

substituted group for: BASICINT: :MY_QUAD. 

“%BASIC-I-CDDSUBGRO, data type in CDD not supported, 


substituted group for: BASICINT: :MY_OCTA. 


The CDD supports the SCALE keyword to specify an implied exponent in 
integer data types, and the BASE keyword to specify that the scale for a 
fixed-point field is to be interpreted in a numeric base other than 10. VAX 
BASIC does not support these integer attributes. Therefore, VAX BASIC 
signals the informational message “CDDATTSCA, CDD specifies SCALE 
for <name> . Not supported”, for fixed-point fields containing a SCALE 
specification and the error message, “CDDATTBAS, CDD attributes for 
<name> are other than base 10”, for fixed-point fields specifying a base 
other than 10. For example: 


CDDL Definition 


define record cdd$top. basic .funnyintegers 
description is 


/* Test of quadword and octaword integer data types */. 


basicint structure. 
my_byte datatype is signed byte scale 2. 
ny_long datatype is signed longword base 8. 
end basicint structure. 
end funnyintegers. 
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Translated RECORD Statement 


1 “%INCLUDE %FROM %CDD "CDD$TOP.BASIC.FUNNYINTEGERS" 
Ci ! Test of quadword and octaword integer data types 
C1 RECORD BASICINT ! UNSPECIFIED 
C1 GROUP MY_BYTE ! SIGNED BYTE 
C1 BYTE BYTE_VALUE 
Ci END GROUP 
C1 LONG MY_LONG ! SIGNED LONGWORD 
C1 END RECORD 


“%BASIC-I-CDDATTSCA, CDD specifies SCALE for BASICINT: :MY_BYTE. Not supported 
%BASIC-E-CDDATTBAS, CDD attributes for BASICINT::MY_LONG are other than base 10 


At compilation time, VAX BASIC also signals these warning errors for 
each reference to fields that are not base 10 or that have a SCALE. 


23.8.3 Floating-Point Data Types 


The CDD supports F_floating, D_floating, G_floating, and H_floating 
data types. These correspond to the BASIC SINGLE, DOUBLE, GFLOAT, 
and HFLOAT data types, respectively. As with fixed-point data types, 

the CDD also allows the specification of scale and base for floating-point 
data types. If a CDD data definition contains a floating-point field that 
specifies a SCALE or BASE, VAX BASIC signals the informational message 
“CDDATTSCA, CDD specifies SCALE for <name> . Not supported” or 
the error message “CDDATTBAS, CDD attributes for <name> are other 
than base 10”. For example: 


CDDL Definition 


define record floats 
description is 


/*Test of floating-point data types*/. 


basicfloat structure. 


my_single datatype is f_floating scale 3. 
my_double datatype is d_floating base 16. 
ny_gfloat datatype is g_floating. 
my_hfloat datatype is h_floating. 
end basicfloat structure. 
end floats. 
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Translated RECORD Statement 


1 “INCLUDE %FROM %CDD "CDD$TOP.BASIC.FLOATS" 
C1 ! Test of floating-point data types 
C1 RECORD BASICFLOAT ! UNSPECIFIED 
C1 GROUP MY_SINGLE ! F_FLOATING 
Ci SINGLE SINGLE_VALUE 
C1 END GROUP 
Ci DOUBLE MY_DOUBLE ! D_FLOATING 
C1 GFLOAT MY_GFLOAT ! G_FLOATING 
C1 HFLOAT MY_HFLOAT ! H_FLOATING 
C1 END RECORD 


“BASIC-I-CDDATTSCA, 1: CDD specifies SCALE for BASICFLOAT: :MY_SINGLE. 
Not supported 

“BASIC-E-CDDATTBAS, 1: CDD attributes for BASICFLOAT: :MY_DOUBLE are 
other than base 10 


In addition, the CDD supports complex floating-point numbers, whereas 
VAX BASIC does not support them. Complex floating-point numbers 
consist of a real and an imaginary part. Each part requires the same 
amount of storage as a simple floating-point number. Therefore, each 
complex floating-point number requires twice as much storage as a simple 
floating-point number. 


If a CDD data definition containing complex numbers is extracted, VAX 
BASIC signals the informational message, “CDDSUBGRO, datatype in 
CDD not supported, substituted group for <field-name> ”, and creates 

a group to contain the field. As before, VAX BASIC uses the data type 
and _VALUE to create the group name, but because each complex number 
contains both a real and an imaginary part, VAX BASIC adds an “_R” to 
the name of the real part and an “_I” to the name of the imaginary part. 
This is illustrated in the following CDD data definition and corresponding 
VAX BASIC RECORD statement. 
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CDDL Definition 


define record cdd$top. basic.complex 
description is 


/* test complex data types */. 


complex structure. 


my_s_complex_t datatype f_floating_complex. 
my_d_complex_1 datatype d_floating._ complex. 
my_g_complex_1 datatype g_floating_complex. 
my_h_complex_i datatype h_floating_complex. 


end complex structure. 
end complex. 


Translated RECORD Statement 


1 “%INCLUDE %FROM %.CDD "CDD$TOP .BASIC.COMPLEX" 
C1 ! test complex data types 
C1 RECORD COMPLEX ! UNSPECIFIED 
C1 GROUP MY_S_COMPLEX_1 ! F_FLOATING_COMPLEX 
C1 SINGLE SINGLE_R_VALUE 
Ci SINGLE SINGLE_I_VALUE 
C1 END GROUP 
Ci GROUP MY_D_COMPLEX_1 ! D_FLOATING_COMPLEX 
C1 DOUBLE DOUBLE_R_VALUE 
C1 DOUBLE DOUBLE_I_VALUE 
C1 END GROUP 
C1 GROUP MY_G_COMPLEX_1 ! G_FLOATING_COMPLEX 
Ci GFLOAT GFLOAT_R_VALUE 
C1 GFLOAT GFLOAT_I_VALUE 
C1 END GROUP 
Ci GROUP MY_H_COMPLEX_1 ! H FLOATING. COMPLEX 
Ci HFLOAT HFLOAT_R_VALUE 
Ct HFLOAT HFLOAT_I_VALUE 
C1 END GROUP 
C1 END RECORD 
Bey ouieUeln a coe a tesetene tone 1 
“%BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 
substituted group for: COMPLEX: :MY_S_COMPLEX_1. 
“%BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 
substituted group for: COMPLEX: :MY_D_COMPLEX_i. 
“%BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 
substituted group for: COMPLEX: :MY_G_COMPLEX_1. 
“%BASIC-I-CDDSUBGRO, 1: data type in CDD not supported, 


substituted group for: COMPLEX: :MY_H_COMPLEX_1. 
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23.8.4 Decimal String Data Types 


The CDD supports the following forms of decimal string data types: 


e LEFT OVERPUNCHED NUMERIC 

e LEFT SEPARATE NUMERIC 

¢ RIGHT OVERPUNCHED NUMERIC 
e RIGHT SEPARATE NUMERIC 

e PACKED DECIMAL 

e UNSIGNED NUMERIC 

¢ ZONED NUMERIC 


VAX BASIC supports only the PACKED DECIMAL decimal string data 
type, which corresponds to the VAX BASIC DECIMAL data type. For all 
other decimal string data types, VAX BASIC creates a group with the same 
name as the CDD subordinate field, and creates a string record component 
to contain the field. For example: 


CDDL Definition 


define record cdd$top.basic.decimalstring 
description is 


/* test decimal string data types */. 


decimalstring structure. 


my_packed_decimal datatype is packed decimal 

size is 5 digits 2 fractions. 
my_zoned_numeric datatype is zoned numeric 

size is 6 digits 2 fractions. 
my_unsigned_numeric datatype is unsigned numeric 


size is 8 digits 4 fractions. 


my_lef_sep_numeric datatype is left separate numeric 
size is 10 digits 3 fractions. 
mny_left_ovpnch_numeric datatype is left overpunched numeric 
size is 5 digits 2 fractions. 
my_right_sep_numeric datatype is right separate numeric 
size is 3 digits 1 fractions. 
ny_right_ovpnch_numeric datatype is right overpunched numeric 


size is 4 digits 2 fractions. 
end decimalstring structure. 
end decimalstring. 
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Translated RECORD Statement 


1 “INCLUDE %FROM %CDD "CDD$TOP .BASIC.DECIMALSTRING" 
C1 ! test decimal string data types 
“C1 RECORD DECIMALSTRING ! UNSPECIFIED 
Ci DECIMAL(5 ,2 ) MY_PACKED_DECIMAL ! PACKED DECIMAL 
Ci GROUP MY_ZONED_NUMERIC ! ZONED NUMERIC ! 
C1 STRING STRING_VALUE = 6 
Ci END GROUP 
Ci GROUP MY_UNSIGNED_NUMERIC ! UNSIGNED NUMERIC 
C1 STRING STRING_VALUE = 8 
C1 END GROUP 
Ci GROUP MY_LEF_SEP_NUMERIC ! NUMERIC LEFT 
! SEPARATE 
C1 STRING STRING_VALUE = 11 
C1 END GROUP 
C1 GROUP MY_LEFT_OVPNCH_NUMERIC ! NUMERIC LEFT 
! OVERPUNCHED 
C1 STRING STRING_VALUE = 5 
C1 END GROUP 
Ci GROUP MY_RIGHT_SEP_NUMERIC ! NUMERIC RIGHT 
! SEPARATE 
C1 STRING STRING_VALUE = 4 
Ci END GROUP 
Ci GROUP MY_RIGHT_OVPNCH_NUMERIC ! NUMERIC RIGHT 
! OVERPUNCHED 
Ci STRING STRING_VALUE = 4 
Ci END GROUP 
Ci END RECORD 
“%BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: DECIMALSTRING: :MY_ZONED_NUMERIC. 
“%BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: DECIMALSTRING: :MY_UNSIGNED_NUMERIC. 
“%BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: DECIMALSTRING: :MY_LEF_SEP_NUMERIC. 
“%BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: DECIMALSTRING: :MY_LEFT_OVPNCH_NUMERIC. 
%BASIC-I-CDDSUBGRO, data type in CDD not supported, 
substituted group for: DECIMALSTRING: :MY_RIGHT_SEP_NUMERIC. 
“BASIC-I-CDDSUBGRO, data type in CDD not supported, 


substituted group for: DECIMALSTRING: :MY_RIGHT_OVPNCH_NUMERIC. 


23.8.5 Other Data Types 
The CDD supports the following additional data types: 


e =6BIT 
e DATE 
e POINTER 
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¢ UNSPECIFIED 
e VIRTUAL 


VAX BASIC does not support these data types. VAX BASIC translates 
these data types by signaling the informational message “CDDSUBGRO, 
data type in CDD not supported, substituted group for: <field name> ”, 
and creates a group to contain the field. See Table 23-2 for a description 
of how VAX BASIC translates these data types. 


If you extract a CDD definition that contains a BIT field, the field must be 
a multiple of 8 bits (1 byte). This means that the following field must be 
aligned on a byte boundary. If the following field is not aligned on a byte 
boundary, VAX BASIC signals the error “CDDBITFLD, field <name> 
from CDD has bit offset or length”. 
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Chapter 24 


CDD/Plus Support in VAX BASIC 


This chapter explains the capabilities of CDD/Plus and how a VAX BASIC 
user can take advantage of them. This chapter only applies to you if you 
have CDD/Plus Version 4.0 or later installed on your system. 


24.1 Introduction to CDD/Plus 


VAX BASIC Version 3.3 and higher supports CDD/Plus Version 4.0 
features. In addition to supporting features available in VAX CDD (see 
Chapter 23), VAX BASIC supports dependency recording. Dependency 
recording allows you to record (or track) what programs use a CDD/Plus 
data definition. It helps you evaluate the effort needed to change a record 
definition by identifying the modules that need to be modified and/or 
recompiled. 


To support dependency recording, CDD/Plus uses a dictionary structure 
known as CDO-format. (The type of dictionary used in CDD versions 
prior to Version 4.0 is known as DMU-format.) You can have many CDO- 
format dictionaries in use on a VMS system (but only one DMU-format 
dictionary). The two types of dictionaries can coexist on a system and a 
program can refer to data definitions in both types. 


When dependency recording is in effect, the VAX BASIC compiler updates 
the CDO-format dictionary to show what dictionary entities the program 
uses. A dictionary entity is any object stored in a CDD dictionary, such as 
as a data definition or form definition. 
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In addition to supporting the functionality of the DMU-format dictionary, 
a CDO-format dictionary allows many additional capabilities that are 
useful to VAX BASIC applications. Using CDD/Plus gives BASIC users 
the following capabilities: 


e Defining and managing data definitions using the CDO utility 


e Reading existing DMU-format dictionaries from CDO 


¢ Referring to CDO-format dictionaries distributed over multiple nodes 
in the network 


e Creating, accessing, and controlling data definitions at the field defini- 
tion level 


e Forming relationships between CDO dictionary definitions, possibly 
connecting definitions from multiple nodes in the network 


e Tracking the use of dictionary-defined information 
¢ Querying CDD/Plus to learn what relationships exist 


When you compile a program that contains references to data definitions 
in a DMU-format dictionary, the data definitions are included in your 
program, but the DMU-format dictionary cannot be updated to show that 
the program uses those data definitions and depends on their continued 
integrity. CDO-format dictionaries offer the additional capability of 
recording dependency relationships between programs and the dictionary 
entities that they use. 


24.2 CDD/Plus Concepts 


This section introduces background concepts that distinguish CDD/Plus 
Version 4.0 from previous versions of the CDD. 
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24.2.1. Dictionary Formats 


CDD/Plus allows two types of dictionaries: 


The DMU-format dictionary 


You create and manipulate a DMU-format dictionary using the DMU, 
CDDL, and CDDV utilities. This type of dictionary was the only 
format available prior to Version 4.0 of the Common Data Dictionary. 


The CDO-format dictionary 


You create and manipulate a CDO-format dictionary using the CDO 
utility and the CDD/Plus Call Interface. Some of the advantages of 
CDO-format dictionaries have been mentioned previously and will be 
clarified in later sections. 


These two types of dictionaries can co-exist on a system to form one 
logical directory structure. CDD/Plus uses a special dictionary, known 
as the compatibility dictionary, that allows an application to refer to 
dictionary definitions without concern about which type of dictionary 
format the definitions are stored in. 


The compatibility dictionary is a CDO-format dictionary whose directory 
hierarchy matches that of the DMU-format dictionary (if any) on the 
system. 


NOTE 


The compatibility dictionary is an installation option for CDD 
/Plus. Even if you do not have a compatibility dictionary, 

an application program can refer to both types of dictionary. 

In this case, the user must be careful to refer to CDO-format 
dictionaries with an anchor origin path name, and to the DMU- 
format dictionary with a CDOD$TOP path name. Anchor origin 
path names are described in the next section. 


Refer to CDD/Plus documentation for detailed information on the CDO 
utility and the compatibility dictionary. 
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24.2.2 Dictionary Path Names 


To access dictionary definitions, you must specify a path name in the 
%INCLUDE %FROM %CDD or %REPORT %DEPENDENCY directive. 
The path name tells CDD where to locate a particular data definition in its 
directory. A CDD path name consists of a string of names separated by 
periods and enclosed in quotation marks. 


The origin is the top, or root, of a dictionary directory. This directory 
contains other dictionary directories, subdictionary directories and objects. 
For example: 


%INCLUDE %FROM %CDD "CDD$TOP. BASIC. EMPLOYEE_DATA" 


In this example, the path name CDD$TOP.BASIC.EMPLOYEE_DATA 
points to the root dictionary directory, CDD$TOP. The root directory 
CDD$TOP contains the dictionary directory BASIC, which in turn contains 
the object EMPLOYEE_DATA, a data definition. 


VAX BASIC allows three types of valid path name parameters when 
referring to CDO dictionary definitions. They differ in the method of 
specifying the dictionary origin. 
e Dictionary anchor path name 
An anchor path name begins with an anchor, which is a VMS 
directory specification, as the dictionary origin. The anchor spec- 
ifies the VMS directory that contains the CDO dictionary. This is 


known as the CDO naming convention. In the following example, 
MYNODE::DISK$2:[MYDIRECTORY] is the anchor: 


MYNODE: : DISK$2: [MYDIRECTORY] PERSONNEL . EMPLOYEES_REC 
e CDDS$TOP path name 


You use this to refer to either DMU-format dictionary definitions or 
CDO-format dictionary definitions in a compatibility dictionary. The 
path origin is always CDD$TOP. This is known as the DMU naming 
convention. For example: 


CDD$TOP . PERSONNEL . EMPLOYEES_REC 
¢ Relative path name 


CDD always begins its search at CDD$TOP (or at the anchor you 
specify) unless you define another directory or object to be the start of 
your directory. You can do this by assigning the name of a dictionary 
directory to the logical name CDD$DEFAULT. For example: 
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$ DEFINE CDD$DEFAULT CDD$TOP. BASIC 


Using this command defines the dictionary directory CDD$TOP.BASIC 
as the default start of your directory. You can override the defined 
default by specifying CDD$TOP in a path name. 


You can omit the origin of a path name and specify a relative path 
name. Any path name that does not begin with either CDD$TOP or 
an anchor is automatically appended to the current CDD$DEFAULT. 
For example, you can specify: 


PERSONNEL. EMPLOYEES_REC 


If CDD$DEFAULT is MYNODE::MY$DISK:[MYDIR], the relative path 
name is the same as: 


MYNODE: :MY$DISK: [MYDIR] PERSONNEL. EMPLOYEES_REC. 


Similarly, if CDDS$DEFAULT is CDD$TOP.MYDIR, the relative path 
name is the same as: 


CDD$TOP . MYDIR.PERSONNEL . EMPLOYEES_REC . 


24.2.3 Dictionary Entities 


Several types of entities can exist in a dictionary. DMU-format and CDO- 
format dictionaries each contain record entities, database entities, and form 
entities, for example. 


When you compile a program with CDD/Plus support enabled, the 
compiler creates a construct known as a compiled module entity in 
the CDO-format dictionary. Only CDO-format dictionaries can contain 
compiled module entities. 


A compiled module entity is created for the main program and each 
SUB, PICTURE subprogram, and FUNCTION. Each compiled module 
entity points to a file entity that contains the fully qualified VMS file 
specification of the .OBJ file. Several compiled module entities can point 
to the same file entity. Compiled module entities are put in the current 
CDD$DEFAULT directory. 


The VAX BASIC compiler creates a compiled module entity (and relation- 
ships in CDD/Plus dictionaries that depend on compiled module entities) 
only if the compilation generates an object file. Therefore, compiled mod- 
ule entities are not generated if you specify the /NOOBJECT qualifier on 

the command line or if the program has compilation errors. 
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24.2.4 Dictionary Relationships 


Relationships occur in a CDO-format dictionary when two or more CDO 
entity definitions are connected in any of several possible ways. For 
example, you can relate a set of field definitions to a record definition by 
including the field names in the record definition. Consider the following 
sequence of CDO commands: 


CDO> DEFINE FIELD REG_DOG_NAME DATATYPE IS TEXT SIZE IS 25 CHARACTERS. 
CDO> DEFINE FIELD BREED DATATYPE IS TEXT SIZE IS 20 CHARACTERS. 

CDO> DEFINE FIELD CALL_NAME DATATYPE IS TEXT SIZE IS 20 CHARACTERS. 
CDO> DEFINE FIELD OWNER_NUMBER DATATYPE IS TEXT SIZE IS 5. 


CDO> DEFINE RECORD DOG_REC. 
cont>REG_DOG_NAME. 
cont>BREED. 

cont>CALL_NAME. 
cont>OWNER_NUMBER. 

cont>END RECORD. 


This sequence defines four field entities initially, and then defines a record 
entity containing those four fields. Thus, CDD/Plus creates a relationship 
between the record DOG_REC and each field that DOG—REC uses. 


You can create other types of relationships from a VAX BASIC program 
by using %INCLUDE and %REPORT directives in conjunction with the 
compilation qualifier /DEPENDENCY_DATA. Later sections will show 

you how to do that. 


See CDD/Plus documentation for detailed information about relationships 
in a CDO-format dictionary. 


24.3 Using CDD/Plus with VAX BASIC 


When dependency recording is in effect, the compiler updates the CDO- 
format dictionary to show what dictionary data entities are used by 

the program (in other words, the data dependencies created by the 
compilation). 


To take advantage of dependency recording, the VAX BASIC user must do 
the following: 


e Use either or both of two VAX BASIC lexical directives in the 
source program, %INCLUDE %FROM %CDD and %REPORT 
% DEPENDENCY, to define the dependency relationships you want to 
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create between your program and definitions in the the CDO-format 
dictionary. These directives will be described further in later sections. 


e Establish a CDO-format dictionary as CDD$DEFAULT. 


e Include the /DEPENDENCY_DATA qualifier in the BASIC command 
that compiles the module. 


24.3.1 The /DEPENDENCY_DATA Qualifier 


When you compile a program that references CDO-format data definitions, 
you can include the /DEPENDENCY_DATA qualifier in the BASIC 
command line. That qualifier tells the compiler to create dependency 
relationships (as defined in the program by %INCLUDE and %REPORT 
directives) and update the dictionary to show those relationships. 


To prevent update of the dictionary, specify /NODEPENDENCY_DATA 
(the default). In this case, the compiler can extract record definitions from 
the dictionary (as specified by %INCLUDE %FROM %CDD directives 

in the program), but will not update the dictionary. In other words, the 
compilation will not add compiled module entities and file entities to the 
dictionary, nor create dependency relationships in the dictionary, unless 
you specify the /DEPENDENCY_DATA qualifier. 


24.3.2 Creating Relationships with Included Record Definitions 


In Section 24.2.4, an example defined a record description as a set of fields 
(thus establishing a simple relationship in the CDD between the record 
and its fields). With that record description defined, you can include it in 
a VAX BASIC program. 


With either a DMU-format or CDO-format dictionary, the compiler can 
extract a record description into a program. To accomplish this, you must 
use the %INCLUDE lexical directive in the source program. The format is 
as follows: 


“INCLUDE %FROM %CDD "pathname" 
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For example, the following BASIC source code extracts a record description 
named ADDRESS_REC from the CDD: 


PROGRAM EXAMPLE1 
“INCLUDE %FROM %CDD "“CDD$TOP.SMITH.ADDRESS_REC" 
DECLARE ADDRESS_REC TEST_RECORD 

"First name"; TEST_RECORD: :FIRST_NAME 
"Last name"; TEST_RECORD: : LAST_NAME 
"Address"; TEST_RECORD: : ADDRESS 

"City"; TEST_RECORD: :CITY 
"State" ; TEST_RECORD: :STATE 

"Zip code"; TEST_RECORD: : ZIP_CODE 


INPUT 
INPUT 
INPUT 
INPUT 
INPUT 
INPUT 


PRINT 
PRINT 
PRINT 


TEST_RECORD: : FIRST_NAME; TEST_RECORD: : LAST_NAME 
TEST_RECORD: : ADDRESS 
TEST_RECORD: :CITY; TEST_RECORD::STATE; TEST_RECORD: : ZIP_CODE 


The listing shows the physical content of the record, as in the following 
listing excerpt: 


1 
2 


ONO W 


9 
10 
11 
12 
13 


PROGRAM EXAMPLE1 
%INCLUDE %FROM %CDD "CDD$TOP.SMITH.ADDRESS_REC" 


RECORD ADDRESS_REC ! UNSPECIFIED 
STRING FIRST_NAME = 20 ! TEXT 
STRING LAST_NAME = 30 1 TEXT 
STRING ADDRESS = 40 1 TEXT 
STRING CITY = 20 1 TEXT 
STRING STATE = 2 ! TEXT 
\ 


DECIMAL(5 ,0 ) ZIP_CODE PACKED DECIMAL 


END RECORD 


DECLARE ADDRESS_REC TEST_RECORD 


Ci 

Ci 

Ci 

C1 

Ci 

Ci 

Ci 

Ci 
INPUT 
INPUT 
INPUT 
INPUT 
INPUT 
INPUT 
PRINT 
PRINT 
PRINT 


"First name"; TEST_RECORD: : FIRST_NAME 
"Last name"; TEST_RECORD: : LAST_NAME 
"Address"; TEST_RECORD: : ADDRESS 
"City"; TEST_RECORD: : CITY 
"State" ; TEST_RECORD: : STATE 

"Zip code"; TEST_RECORD: : ZIP_CODE 


TEST_RECORD: :FIRST_NAME; TEST_RECORD: : LAST_NAME 
TEST_RECORD: : ADDRESS 
TEST_RECORD: :CITY; TEST_RECORD: :STATE; TEST_RECORD: : ZIP 


In the case of a CDO-format dictionary, you can also cause the dictionary 
to create and maintain a formal relationship between the record descrip- 

tion and the compiled module entity that represents your program in the 
dictionary. 


This is known as a CDD$COMPILED_DEPENDS_ON relationship. To 
accomplish this relationship, you must specify the /DEPENDENCY_ 
DATA qualifier when you compile the program. 


$ BASIC/DEPENDENCY_DATA EX1.BAS 
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If you specify the /DEPENDENCY_DATA qualifier to the VAX BASIC 
compiler, the compiled module entity is created and updated to reflect the 
fact that your program uses that record. If someone wants to change the 
data definition at a later date, CDO allows that person to find out what 
programs depend on it before doing so. For example: 


CDO> DIRECTORY 
Directory SYS$COMMON: [CDDPLUS] SMITH 


ADDRESS ; 1 FIELD 
ADDRESS_REC; 1 RECORD 
CITY;1 FIELD 
EXAMPLE1 ; 1 CDD$COMPILED_MODULE 
FIRST_NAME; 1 FIELD 
LAST_NAME; 1 FIELD 
STATE; 1 FIELD 
ZIP_CODE; 1 FIELD 


You can use the CDO SHOW USES command to find out what programs 
use a dictionary definition. For example: 


CDO> SHOW USES ADDRESS_REC 

Owners of SYS$COMMON : [CDDPLUS] SMITH. ADDRESS_REC; 1 

| | SYS$COMMON: [CDDPLUS]SMITH.EXAMPLE1;1 (Type : CDD$COMPILED_MODULE) 
| | via CDD$COMPILED_DEPENDS_ON 


You can also use CDO to find out what dictionary definitions a program 
uses. For example: 


CDO> SHOW USED_BY EXAMPLE1 

Members of SYS$COMMON: [CDDPLUS] SMITH .EXAMPLE1; 1 

| EX1 (Type : CDD$FILE) 

| | via CDD$IN_FILE 

|  SYS$COMMON: [CDDPLUS]SMITH.ADDRESS_REC;1 (Type : RECORD) 
| | via CDD$COMPILED_DEPENDS_ON 
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24.4 Creating Relationships for Referenced Dictionary Entities 


The compiler can create a relationship between a compiled module entity 
and any dictionary entity that a program references (such as an Rdb/VMS 
database or a form definition). The referenced dictionary entity is not 
copied to the program. Instead, the compiled program simply references 
the dictionary entity at run time, or with the help of a preprocessor. 


To create such relationships in a BASIC program, you must use a 

% REPORT %DEPENDENCY lexical directive in the source program 
and specify the /DEPENDENCY_DATA qualifier when you compile the 
program. The format is as follows: 


% REPORT %DEPENDENCY “pathname” [“relationship-type’”] 


The “pathname” parameter identifies the dictionary item that the compiled 
object module references. The path name can specify a CDO-format 
dictionary item (with an anchor as the first element), or it can specify a 
CDO-format item in the compatibility dictionary (which can be specified 
either as a CDD$TOP path name or as an anchor path name). See 
Section 24.2.2 for a full description of the path name options. 


The optional “relationship-type” parameter determines the type of re- 
lationship by specifying a CDD/Plus protocol. There are many valid 
values; refer to CDD/Plus documentation for full information. The most 
commonly-used type of relationship for VAX BASIC users is: 


CDD$COMPILED_DEPENDS_ON 


This specifies a relationship that links a compiled object module to the 
element that goes into the compilation. This is the default. 


The %REPORT %DEPENDENCY directive is meaningful only when the 
following three conditions are true: 


¢ /DEPENDENCY_DATA qualifier is specified in the BASIC command 
line. (If it is not specified, the compiler checks syntax but does not 
update the dictionary to reflect this usage of the item.) 


e Your current CDD$DEFAULT points to a directory in a CDO 
dictionary. 


e The dictionary item specified by pathname is in a CDO-format dictio- 
nary. (No relationship can be created in a DMU-format dictionary.) 
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Suppose the VAX BASIC program DOG-REPORT.BAS contains the 
following directive: 


YREPORT %,DEPENDENCY "DISK1$: [CDDPLUS. BASIC] SMITH . DOG_DATABASE" 

Use the /DEPENDENCY_DATA qualifier when you compile the program: 
$ BASIC/DEPENDECY_DATA DOG_REPORT 

After the compilation, the dictionary contains the following: 


CDO> DIR 
Directory DISK1$: [CDDPLUS. BASIC] SMITH 


BREED ; 1 FIELD 

CALL_NAME; 1 FIELD 
DOG_REPORT$MAIN; 1 CDD$COMPILED_MODULE 
DOG_DATABASE; 1 CDD$DATABASE 
DOG_INFORMATION; 1 CDD$RMS_DATABASE 
DOG_REC; 1 RECORD 

OWNER_NUMBER ; 1 FIELD 

REG_DOG_NAME; 1 FIELD 


CDO> SHOW USES DOG_DATABASE 


Owners of DISK1$: [CDDPLUS.BASIC]SMITH.DOG_DATABASE; 1 
| DISK1$: [CDDPLUS .BASIC]SMITH.DOG_REPORT$MAIN;1 (Type : CDD$COMPILED_MODULE) 
| | via CDD$COMPILED_DEPENDS_ON 


CDO> SHOW USED_BY DOG_REPORT$MAIN 

Members of DISK1$: [CDDPLUS.BASIC]SMITH.DOG_REPORT$MAIN; 1 

| DOG_REPORT (Type : CDD$FILE) 

| | via CDD$IN_FILE 

| DISK1$: [CDDPLUS.BASIC]SMITH.DOG_DATABASE;1 (Type : CDD$DATABASE) 
| | via CDD$COMPILED_DEPENDS_ON 


24.5 Specifying a CDD History List Entry 


When your VAX BASIC program accesses the CDD, you have the option 
of entering a history list entry in the CDD data base. The history list entry 
provides a history of users that access the CDD. 


You enter a history list entry by specifying the DCL command qualifier 
/AUDIT. For example: 


$ BASIC/DEPENDENCY_DATA/AUDIT="History text goes here" EX1.BAS 


Note that instead of typing the text directly on the command line, you can 
also specify a file specification that contains the history entry. 
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When you specify /AUDIT, a history list entry is created for each com- 
piled module entity that the compilation creates. In addition, the compila- 
tion will add a history list entry to each data definition that your program 
extracts with the %INCLUDE %FROM %CDD directive. 


You can display history list information using the CDO utility. For 
example: 


CDO> SHOW GENERIC CDD$COMPILED_MODULE EXAMPLE1 /AUDIT 
Definition of EXAMPLE1 (Type : CDD$COMPILED_MODULE) 
| History entered by SMITH ([SMITH]) 

| using VAX BASIC V3.3 

| to CREATE definition on 25-APR-1988 13:04:01.48 
| Explanation: 

| "History text goes here" 
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Appendix A 
Compile-Time Error Messages 





This appendix describes compile-time and compiler command errors, their 
causes, and the user action required to correct them. 


A.1 Compile-Time Errors 


VAX BASIC diagnoses compile-time errors and: 


¢ Indicates the program line that generated the error or errors 
e Displays this program line 


e Shows you the location of the error or errors and assigns a number to 
each location for future reference 


e Displays the mnemonic, statement number within the line, the loca- 
tion number as previously displayed, and the message text. This is 
repeated for each error in the line. 


VAX BASIC repeats this procedure for each error diagnosed during compi- 
lation. The error message format for compile-time errors is: 


“%BASIC-<1>-<mnemonic>, <n>: <message> 
</> 


Is a letter indicating the severity of the error. The severity indicator can be 
one of the following: 


e I, indicating information 
e W, indicating a warning 
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e —E, indicating an error 
e F, indicating a severe error 


<mnemonic> 
Is a 3- to 9-character string that identifies the error. Error messages in this 
appendix are alphabetized by this mnemonic. 


<n>: 
Is the nth error within the line’s “picture”. 


<message> 
Is the text of the error message. 


For example: 


Diagnostic on source line 1, listing line 1, BASIC line 10 


10 DECLARE REAL BYTE A, A 
shea R Ripa Areas AM By Sega a, se Lis ciesarncd 


“BASIC-E-CONDATSPC, 1: conflicting data type specifications 
“%BASIC-E-ILLMULDEF, 2: illegal multiple definition of name A 


This display tells you that two errors were detected on line 10; VAX BASIC 
displays the line containing the error, then prints a “picture” showing you 
where the errors were detected. In the example, the picture shows a 

“1” under the keyword BYTE and a “2” under the second occurrence of 
variable A. The following line shows you: 


e The error mnemonic CONDATSPC 
¢ Which error in the line’s “picture” is referred to by the mnemonic 
¢ The message associated with that error 


In this case, the error message tells you that there are two contradictory 
data-type keywords in the statement. The next line shows you the same 
type of information for the second error; in this case, the compiler detected 
multiple declarations of variable A. 


If a compilation causes an error of severity I or W, the compilation 
continues and produces an object module. If a compilation causes an 
error of severity E, the compilation continues but produces no object 
module. If a compilation causes an error of severity F, the compilation 
aborts immediately. 


A-2 Compile-Time Error Messages 


The following is an alphabetized list of compilation error messages: 


ACTARGMUS, actual argument must be specified 


Explanation: ERROR - A DEF function reference contains a null 
argument, for example, FNA(1,,2). 


User Action: Specify all arguments when referencing a DEF 
function. 


ALLOCSML, allocated area may be too small for section 


Explanation: WARNING - A MAP or COMMON with the same 
name exists in more than one program module, and the first one 
encountered by the compiler is smaller than the subsequent ones. 


User Action: VAX BASIC first allocates MAP and COMMON 
areas in the main program, then MAP and COMMON areas in 
subprograms, in the order in which they were loaded. Thus, you 
can avoid this error by loading modules with the largest MAP 

or COMMON first. However, it is better practice to make MAP 
and COMMON areas equal in size. 


AMBRECCOM, ambiguous RECORD component 


Explanation: ERROR - The program contains an ambiguous 
RECORD component reference, for example, A::D when both 
A::B::D and A::C::D exist. 


User Action: Remove the ambiguity by fully specifying the 
record component. 
AMPCONILL, & continuation is illegal after % INCLUDE directive 


Explanation: ERROR - A program contains an %INCLUDE 
directive followed by an ampersand continuation to another 
statement. For example, the following is illegal: 


2300 “INCLUDE “FROM %CDD "CDD$TOP.PERSONNEL.EMPLOYEE" & 
GOTO 3000 


Ampersand continuation of the %INCLUDE directive is legal, 
however. 


User Action: Recode to eliminate the line continuation or use 
backslash continuation. 
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AMPCONREP, & continuation is illegal after %REPORT directive 


Explanation: ERROR - A program contains a %REPORT di- 
rective followed by an ampersand continuation to another 
statement. For example, the following is illegal: 


2300 “%REPORT %DEPENDENCY "CDD$TOP.PERSONNEL.EMPLOYEE.COURSE_FORM" & 
GOTO 3000 


Ampersand continuation of the % REPORT directive itself is 
legal, however. 


User Action: Recode to eliminate the line continuation or use 
backslash continuation. 


ANSDEFMUS, ANSI DEF must be defined before reference 


Explanation: ERROR - A program compiled with the /ANSI_ 
STANDARD qualifier contains a reference to a DEF function 
before the function definition. 


User Action: Renumber the line containing the function def- 
inition so that the definition precedes all references to the 
function. 


ANSILNREQ, a line number is required on first line for ANSI 


Explanation: ERROR - When you specify the /ANSI qualifier, a 
program must have a line number on the first line for the ANSI 
qualifier. 


User Action: Supply a line number on the first line. 


ANSKEYSPC, keywords must be delimited by spaces in /ANSI 


Explanation: ERROR - A program compiled with the /ANSI_ 
STANDARD qualifier contains a line where two elements (two 
keywords, a keyword and a line number, or a keyword and a 
string constant) are not separated by at least one space. For 
example, PRINT“Hello’. 


User Action: Delimit all keywords, line numbers, and string 
constants with at least one space. 
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ANSLINDIG, ANSI line number may not exceed 4 digits 


Explanation: ERROR - A program compiled with the /ANSI_— 
STANDARD qualifier contains a line number with more than 4 
digits, that is, a number greater than 9999. 


User Action: Renumber the program lines so that no line 
number exceeds 9999. 


ANSLINNUM, ANSI line numbers must begin in column 1 


Explanation: ERROR - A program compiled with the /ANSI_ 
STANDARD qualifier contains a line number preceded by one or 
more spaces or tabs. 


User Action: Remove any spaces and tabs that precede the line 
number. 


ANSREQREA, ANSI requires REAL default type 


Explanation: ERROR - The /ANSILSTANDARD qualifier 
conflicts with the /TYPE_DEFAULT qualifier. 


User Action: Do not specify a default data type other than 
REAL. REAL is the default. 


Compile-Time Error Messages A-4.1 


ANSREQSCA, ANSI requires SCALE 0 


Explanation. ERROR - The /ANSI_STANDARD qualifier 
conflicts with the /SCALE qualifier. 


User Action. Do not specify a scale factor. 


ANSREQSET, ANSI requires SETUP 


Explanation. ERROR - The /ANSI_STANDARD qualifier 
conflicts with the /NOSETUP qualifier. 


User Action. Do not specify /NOSETUP. 


ANYDIMNOT, dimension checking not allowed on ANY 


Explanation. ERROR - Both a datatype of ANY and a DIM 
clause were specified in an EXTERNAL statement. 


User Action. Remove the DIM clause from the EXTERNAL 
statement. ANY implies either scalar or array. 


ANYNOTALL, ANY not allowed on EXTERNAL PICTURE 


Explanation. ERROR - An attempt was made to specify the 
ANY keyword on an EXTERNAL PICTURE declaration. This 
is not allowed because the ANY data type should be used for 
calling non-BASIC procedures only. 


User Action. Remove the ANY keyword from the EXTERNAL 
PICTURE declaration. 


APPMISNUM, append file missing line number on first line 


Explanation. ERROR - An attempt was made to append a source 
file that does not contain a line number on the first line. 


User Action. Put a line number on the first line of the appended 
file. 
APPNOTALL, append not allowed on programs without line numbers 


Explanation. ERROR - The APPEND command cannot be used 
on a program without line numbers. 


User Action. Use an include file. 
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ARESTYMUS, area style must be “HOLLOW”, “SOLID”, “PATTERN” or 
“HATCH” 


Explanation. ERROR - You specified an invalid value in the SET 
AREA STYLE statement. 


User Action. Specify one of the values listed in the message. 


AREREQTHR, AREA output requires at least 3 X,Y points 


Explanation. ERROR - An AREA graphic output statement 
specifies less than 3 points. 


User Action. Specify at least 3 points in the AREA graphic 
output statement. 


ARGERKR, illegal argument for command 


Explanation. ERROR - An argument was entered for a command 
that does not take an argument, or an invalid argument was 
entered for a command, for example, SCALE A or LIST A. 


User Action. Reenter the command with the proper arguments. 


ARRMUSHAY, array must have 1 dimension 


Explanation. ERROR - An array with multiple dimensions is 
specified where a 1 dimensional array is required. 


User Action. Specify an array that has 1 dimension. 


ARRMUSELE, array must have at least 4 elements 


Explanation. ERROR - You specified an array with less than 
four elements. This statement requires an array with at least four 
elements in it. 


User Action. Supply an array declared as having at least 4 
elements. 


ARRNAMREQ, array names only allowed 


Explanation. ERROR - The type of variable name required must 
be an array name. 


User Action. Change the variable name to an array name. 
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ARRNOTALL, array <name> not allowed in DEF declaration 


Explanation. ERROR - The parameter list for a DEF function 
definition contained an entire array. 


User Action. Remove the array specification. Passing an entire 
array as a parameter to a DEF function is not allowed. 


ARRTOOBIG, named array <array-name> is too large 


Explanation. ERROR - An array requires less than (2°29 - 1) 
bytes of storage. 


User Action. Reduce the size of the array. 


ATROVRVAKR, attributes of overlaid variable <name> don’t match 


Explanation. ERROR - A variable name appears in more than 
one overlaid MAP; however, the attributes specified for the 
variable are inconsistent. 


User Action. If the same variable name appears in multiple 
overlaid MAPs, the attributes (for example, data type) must be 
identical. 


ATRPRIREF, attributes of prior reference to <name> don’t match 


Explanation. WARNING - A variable or array is referenced 
before the MAP that declares it. The attributes of the referenced 
variable do not match those of the declaration. 


User Action. Make sure that the variable or array has the same 
attributes in both the reference and the declaration. 


ATTGTRZER, graphics attribute value must be greater than zero 


Explanation. ERROR - You specified a negative value when a 
positive value is required. 


User Action. Supply a value greater than zero. 


BADFMTSTR, invalid PRINT USING format string 


Explanation. ERROR - The PRINT USING format string speci- 
fied is not valid. 


User Action. Supply a valid PRINT USING format string. 
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BADLOGIC, internal logic error detected 
Explanation. ERROR - An internal logic error was detected. 


User Action. This error should never occur. Please submit a 
Software Performance Report with a machine-readable copy of 
the source program. 


BADNO, qualifier <name> does not accept ‘NO’ 


Explanation. ERROR - A qualifier that does not allow a 'NO' 
prefix was entered. For example, NODOUBLE. 


User Action. Select the proper qualifier. In the example, the 
complementary form of DOUBLE is SINGLE. 


BADPROGMM, error in program name 


Explanation. ERROR - The program name is longer than 39 
characters or contains invalid characters. 


User Action. Change the program name to be less than or equal 
to 39 characters and make sure that it contains only letters, 
digits, dollar signs, and underscores. 


BADVALUE, <text> is an invalid keyword value 


Explanation. FATAL - The command supplied an invalid value 
for a keyword. 


User Action. Supply a valid value. 


BASICHLB, BASIC’s HELP library is not installed on this system 


Explanation. INFORMATION - A HELP command was entered 
and the VAX BASIC BASIC HELP library was not available. 


User Action. See your system manager. 


BIFREQNUM, built in function requires numeric expression 


Explanation. ERROR - A reference to a VAX BASIC built-in 
function contains a string instead of a numeric expression. 


User Action. Supply a numeric expression. 
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BIFREQSTR, built in function requires string expression 


Explanation. ERROR - The program specifies a numeric expres- 
sion for a built-in function that requires a string argument. 


User Action. Supply a string expression for the built-in function. 


BLTFUNNOT, built in function not supported 


Explanation. ERROR - The program contains a reference to a 
built-in function not supported by this version of VAX BASIC. 


User Action. Remove the function reference. 


BOTBOUSPE, bottom boundary must be less than the top boundary 


Explanation. ERROR - In a statement that specifies a viewport 
or windowsize, you specified a bottom boundary that is greater 
than or equal to the corresponding top boundary. 


User Action. Correct the bottom boundary so that it is less than 
the top boundary. 
BOUCANNOT, bound cannot be specified for array 


Explanation. ERROR - An EXTERNAL statement declaring a 
SUB or FUNCTION subprogram specifies bounds in an array 
parameter, for example: 


EXTERNAL SUB XYZ (LONG DIM(1,2,3)) 


User Action. Remove the array parameter’s bound specifications. 
When declaring an external subprogram, you can specify only 
the number of dimensions for an array parameter. For example: 


EXTERNAL SUB XYZ (LONG DIM(,,)) 


BOUMUSTBE, bounds must be specified for array 


Explanation. ERROR - The program contains an array declara- 
tion that does not specify the bounds (maximum subscript value), 
for example: 


DECLARE LONG A(,) 
User Action. Supply bounds for the declared array, for example: 


DECLARE LONG A(50,50) 
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CANCON, can’t continue 


Explanation. FATAL - A CONTINUE command was typed after 
changes had been made to the source code. 


User Action. After changes have been made to the source code, 
you can run the program, but you cannot continue it. 


CAUNOTALL, CAUSE statement not allowed in error handler 


Explanation. ERROR - A CAUSE statement is specified within 
an error handler. 


User Action. Remove the CAUSE statement from the error 
handler. 


CDDACCERR, CDD access error 


Explanation. ERROR - The CDD detected an error on an at- 
tempted CDD record extraction. VAX BASIC displays the CDD 
error. 


User Action. Take action based on the associated CDD error. 


CDDACCITE, CDD error while accessing item <field-name> of record 


Explanation. ERROR - The CDD reported an error when access- 
ing the field. The CDD record definition is corrupt, or there is an 
internal error in either VAX BASIC or the CDD. 


User Action. If the problem is not in the CDD definition, please 
submit an SPR with the source code of a small program that 
produces this error. 


CDDACCREC, CDD error while accessing record 


Explanation. ERROR - The CDD reported an error when access- 
ing the record. The CDD record definition is corrupt or there is 
an internal error in either VAX BASIC or the CDD. 


User Action. If the problem is not in the CDD definition, please 
submit an SPR with the source code of a small program that 
produces this error. 
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CDDADJBOU, adjusted bounds for dimension <number> of <array> 
to be zero based 


Explanation. INFORMATION - The CDD contains an array field 
with a lower bound that is not zero. VAX BASIC adjusts the 
bound so that the array is zero based. 


User Action. None. 


CDDALCOFF, please submit an SPR—CDD inconsistent with allocated 
offset for <field-name> 


Explanation. FATAL - The offset of a field within a VAX BASIC 
RECORD differs from the offset specified by the CDD for that 
record. 


User Action. Please submit an SPR with the source code of a 
small program that produces this error. 


CDDALCSIZ, please submit an SPR—CDD inconsistent with allocated 
size for <field-name> 


Explanation. FATAL - The amount of storage allocated for a 
field in a VAX BASIC RECORD differs from the amount specified 
by the CDD for that record. 


User Action. Please submit an SPR with the source code of a 
small program that produces this error. 


CDDALCSPN, please submit an SPR—CDD inconsistent with allocated 
span for <field-name> 


Explanation. FATAL - The amount of storage allocated by a VAX 
BASIC RECORD for an array differs from the amount specified 
by the CDD for that record. 


User Action. Please submit an SPR with the source code of a 
small program this error. 


CDDAMBEFELD, ambiguous field name <name> for <RECORD-name> 


Explanation. ERROR - More than one CDDL structure share the 
same level and the same name. 


User Action. Change the CDD definition so that the structures 
have different names. 


Compile-Time Error Messages A-11 


CDDATTBAS, CDD attributes for <name> are other than base 10 


Explanation. ERROR - A field in a CDD definition uses the 
BASE keyword. This warns you that the numeric field is not 
interpreted as a base 10 number. 


User Action. Remove the BASE attribute in the CDD or avoid 
using the field. 


CDDATTDAT, CDD data type attribute not permitted for GROUP 


Explanation. ERROR - A CDD definition specified a data type 
after the CDD STRUCTURE keyword. VAX BASIC translates 

STRUCTURE to a VAX BASIC RECORD or GROUP statement. 
These VAX BASIC statements do not allow data type attributes. 


User Action. Change the CDD definition. 


CDDATTDIG, DIGITS attribute of <field-name> not supported for 
datatype 


Explanation. INFORMATION - The field contains a CDD fixed- 
point data-type that specifies the number of allowed digits. This 
warning tells you that VAX BASIC interprets the field as BYTE, 
WORD, or LONG and does not support the DIGITS attribute for 
this data type. | 


User Action. None. 
CDDATTSCA, CDD specifies SCALE for <RECORD-component> . Not 
supported. 


Explanation. INFORMATION - A field in a CDD definition 
uses the SCALE keyword. This warns you that the field has an 
implied exponent. 


User Action. Remove the SCALE attribute in the CDD, or avoid 
using the field. 


CDDATTTXT, CDD TEXT attribute for group <group-name> ignored 


Explanation. INFORMATION - A CDD record definition speci- 
fies a data type of TEXT for the entire record. 


User Action. None. VAX BASIC ignores the TEXT attribute and 
substitutes the UNSPECIFIED attribute. 
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CDDBASNAM, CDD specified BASIC name <name> has illegal form 


Explanation. ERROR - The VAX BASIC name specified in the 
CDD record definition is a reserved keyword or contains an 
illegal character. 


User Action. Change the invalid field name. 


CDDBITFLD, field <field-name> from CDD has bit offset or length 


Explanation. ERROR - A CDD field does not start on a byte 
boundary. 


User Action. Change the bit field in the CDD to have a length 
that is a multiple of 8 bits. 


CDDCOLMAJ, <array-name> from CDD is a column major array 


Explanation. ERROR - An array specified in a CDD definition 
is column-major rather than row-major. Thus it is incompatible 
with VAX BASIC arrays. 


User Action. Change the CDD definition to be a row-major 
array. 


CDDDIGERR, decimal digits of <value> in CDD out of range for 
<field-name> 


Explanation. ERROR - A packed numeric CDD specifies more 
than 31 digits. 


User Action. Reduce the number of digits specified in the CDD 
definition. 
CDDDIMNOT, RECORD cannot be dimensioned 


Explanation. ERROR - A CDD definition is itself an array. This 
is incompatible with VAX BASIC RECORDs, which can contain 
arrays but cannot be arrays. 


User Action. None. You cannot access CDD definitions that are 
arrays. 
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CDDDUPREC, RECORD <name> from CDD has duplicate name 


Explanation. ERROR - The CDD record name conflicts with a 
previous RECORD name. The previous RECORD name may be 
a standard VAX BASIC RECORD or another CDD record. 


User Action. Remove one of the duplicate definitions. 


CDDFLDNAM, field name missing 


Explanation. ERROR - The CDD definition contains a field that 
is not named. 


User Action. Supply a field name for the CDD definition. 


CDDINTONLY, % not allowed on <name> with non-integer datatype 


Explanation. ERROR - The % suffix is allowed only on numeric 
data types. 


User Action. Remove the % suffix from the variable name or 
change the datatype keyword. 


CDDLOWBOU, lower bound omitted for dimension <number> of 
<array-name> 


Explanation. ERROR - An array in a CDD definition does not 
specify a lower bound. 


User Action. Check to make sure the omission is not a mistake. 
VAX BASIC supplies a lower bound of zero and continues after 
issuing this warning. 

CDDMAXDIM, <array-name> exceeds maximum dimensions 


Explanation. ERROR - An array in a CDD definition specifies 
more than 32 dimensions. 


User Action. Reduce the number of dimensions in the CDD 
definition. 
CDDNAMKEY, <name> is a BASIC keyword 


Explanation. ERROR - A CDD definition contains a field name 
that is a reserved word in VAX BASIC. 


User Action. Change the name in the CDD definition or supply 
a VAX BASIC name clause. 
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CDDOCCIGN, OCCURS DEPENDING ON clause for <array-name> from 


CDDOFFERR, 


CDD ignored 


Explanation: INFORMATION - The CDD contains an array field 
with a variable number of elements. VAX BASIC creates an array 
large enough for the maximum value. 


User Action: If you modify the array field, be sure also to 
change the field that contains the number of array elements. 


CDD offset error, field <field-name> offsets out of order 


Explanation: ERROR - The CDD definition has been corrupted 
or there is an internal error in either VAX BASIC or the CDD. 


User Action: If the problem is not in the CDD definition, please 
submit an SPR with the source code of a small program that 
produces this error. 


CDDPLUSERR, CDD/Plus access error 


CDDPREERR, 


Explanation: ERROR - CDD/Plus detected an error while 
attempting to record dependency data. VAX BASIC displays the 
CDD/Plus error. 


User Action: Take action based on the associated CDD/Plus 
error. 


decimal precision of <VALUE> in CDD out of range for 
<field-name> 


Explanation: ERROR - The number of fractional digits for a 
packed decimal field is greater than the total number of digits 
specified for that field. 


User Action: Change the number of fractional digits in the CDD 
to be less than or equal to the total number of digits. 


CDDRECFOR, CDD record format is not fixed 


July 1988 


Explanation: ERROR - The CDD supports both variable and 
fixed-length records. VAX BASIC supports only fixed-length 
records. 


User Action: Change the CDD record definition to specify 
fixed-length. 
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CDDRECNAM, record from CDD does not have a record name 


Explanation: ERROR - VAX BASIC uses the field name of the 
outermost structure to name the record, and therefore cannot 
include a CDD record that does not provide a record name. 


User Action: Change the CDD record definition to provide a 
field name for the outermost structure of the record. 

CDDSCAERR, decimal scale of <scale-factor> is out of range for <field> 
from CDD 


Explanation: ERROR - The scale factor for a packed decimal 
CDD field is greater than the number of digits in the field or less 
than zero. 


User Action: Change the scale factor in the CDD definition. 


CDDSCAZER, scale 0 specified for CDD field <field-name> 


Explanation: INFORMATION - A CDD field specifies no scale 
factor for a D_floating field, but the VAX BASIC program 
specifies a non-zero scale factor. 


User Action: Use a scale factor of zero in the VAX BASIC 
program. 
CDDSTRONLY, §$ not allowed on <name> _ with non-string datatype 


Explanation: ERROR - The $ suffix is only allowed on string 
datatypes. 


User Action: Remove the $ suffix from the variable name or 
change the datatype keyword. 

CDDSUBGRO, substituted GROUP for <field-name> . Data type in CDD not 
supported. 


Explanation: INFORMATION - The CDD definition specifies a 
data type that is not native to VAX BASIC. VAX BASIC creates 
a GROUP with the same name as the CDD field and creates 
variable names for the GROUP components. 


User Action: None. 
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CDDTAGIGN, tag value ignored for <field-name> from CDD 


Explanation: INFORMATION - The CDD record definition 
contains a VARIANTS OF. 


User Action: None. VAX BASIC translates the VARIANTS OF 
as if it were a regular variant; however, the tag value is ignored. 
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CDDUNSDAT, data type specified in CDD for <field-name> not 
supported 


Explanation. ERROR - The data type specified for a field is not 
supported by VAX BASIC. 


User Action. Change the data type in the CDD record definition. 


CDDUPPBOU, upper bound omitted for dimension <number> of 
<array-name> 


Explanation. ERROR - An array in a CDD definition does not 
specify an upper bound. 


User Action. Specify an upper bound in the CDD definition. 


CDDVARELD, field <name> from CDD has variable offset or length 


Explanation. ERROR - A CDD field can be either variable or 
fixed-length. VAX BASIC supports only fixed-length fields. 


User Action. Change the CDD definition. 


CHAEXPMUS, channel expression must be numeric 


Explanation. ERROR - The program contains a nonnumeric 
channel expression, for example, PUT #A$ 


User Action. Change the channel expression to be numeric. 


CHALINCLA, CHAIN does not support line number clause 


Explanation. ERROR - A CHAIN statement contains a LINE 
keyword and a line number argument. 


User Action. Remove the LINE keyword and the line number 
argument. 


CHANGES, unsaved change has been made, CTRL/Z or EXIT to exit 


Explanation. WARNING - A VAX BASIC source program in 
memory has been modified, and an EXIT command or CTRL/Z 
has been typed. VAX BASIC signals the error notifying you that 
if you exit from the compiler, the program modifications will be 
lost. 


User Action. If you want to SAVE the program, type SAVE. If 
you do not want to save the program, type EXIT or CTRL/Z. 
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CHANOTALL, CHANGES not allowed on primary key 


Explanation. ERROR - The PRIMARY KEY clause in an OPEN 
statement specifies CHANGES. 


User Action. Remove the CHANGES keyword; you cannot 
change the value of a primary key. 


CHASTAAMB, CHANGE statement is ambiguous 


Explanation. ERROR - A string variable and a numeric array 
have the same name in a CHANGE statement. 


User Action. Change the name of the string variable or the 
numeric array. 


CLIPMUSBE, clipping must be set to “ON” or “OFF” 


Explanation. ERROR - You specified an invalid value in the SET 
CLIP statement. 


User Action. Specify one of the values listed in the message. 


CLOSEIN, error closing <file-name> as input 


Explanation. ERROR - An error was detected while closing an 
input file. 


User Action. Take corrective action based on the associated 
message. 


CLOSEOUT, error closing <file-name> as output 


Explanation. ERROR - An error was detected while closing an 
output file. 


User Action. Take corrective action based on the associated 
message. 


CMDNOTALL, command not allowed on programs without line numbers 


Explanation. ERROR - A command that cannot be used on a 
program without line numbers has been used on a program 
without line numbers. 


User Action. Do not use this command on programs without 
line numbers. 
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CODLENEST, internal code length estimate error. Submit an SPR 


Explanation. FATAL - VAX BASIC has incorrectly estimated the 
size of the generated code for your program. 


User Action. Submit an SPR with the program that caused the 
error. (You can often work around this error by making a simple 
change to your code.) 


COLOUTRAN, color intensities must be in the range 0.0 to 1.0 


Explanation. ERROR - The value specified for color intensity is 
either less than 0.0 or greater than 1.0. 


User Action. Supply a value between 0.0 and 1.0. 


COMMAPALLT, variable <name> not aligned in COMMON/MAP 
<name> 


Explanation. INFORMATION - In a COMMON or MAP, the 
total storage preceding a REAL, WORD, or LONG numeric 
variable is an odd number of bytes. 


User Action. None. In VAX BASIC, numeric data can start on 
any byte boundary. 


COMMAPNEQ, COMMON /MAP area sizes are not equal for section 


Explanation. WARNING - A MAP or COMMON with the same 
name exists in more than one program module, but the size of 
the areas differs. 


User Action. Make the size of the COMMON or MAP areas 
equal in size in all modules. 


COMMAPOVF, COM/MAP <name> is too large 


Explanation. ERROR - The program contains a MAP or 
COMMON longer than (2°31 - 1) longwords. 


User Action. Reduce the length of the COMMON or MAP. 
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CONCOMSYN, conditional compilation cannot be used with /SYNTAX 


Explanation. FATAL - The /SYNTAX_CHECKING qualifier 
is in effect when a program line containing the %IF, %THEN, 
%ELSE, or %END %IF lexical directive was entered. 


User Action. Turn off syntax checking before entering a program 
line containing the %IF, % THEN, %ELSE, or %END %IF lexical 
directive. 


CONDATSPC, conflicting data type specifications 


Explanation. ERROR - The program contains a declarative 
statement containing two or more consecutive and contradictory 
data type keywords, for example, DECLARE REAL BYTE. 


User Action. Remove one of the data type keywords or make 
sure that the keywords refer to the same generic data type. For 
example, DECLARE REAL SINGLE is valid. 

CONEXPREQ, constant expression required 


Explanation. ERROR - A statement specifies a variable, built-in 
function reference or exponentiation where a constant is required. 


User Action. Supply an expression containing only literals or 
declared constants or remove the exponentiation operation. 
CONTARNOT, CONTINUE target not legal in detached error handlers 


Explanation. ERROR - A CONTINUE statement within a 
detached WHEN block error handler contains a target. 


User Action. Remove the target line number or label from the 
CONTINUE statement or use an attached error handler. 
CONIS_INC, constant is inconsistent with the type of <name> 


Explanation. ERROR - A DECLARE CONSTANT statement 
specifies a value that is inconsistent with the data type of 
the constant, for example, a BYTE value specified for a REAL 
constant. 


User Action. Change the declaration so that the data type of the 
value matches that of the constant. 
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CONIS_NEE, <item> requires conditional expression 


Explanation. ERROR - A CASE or IF keyword is immediately 
followed by a floating-point or string expression. 


User Action. Supply a conditional expression (relational, logical, 
or integer). 
CONLFTSID, constant <name> _ not allowed on left side of assignment 


Explanation. ERROR - The program tries to assign a value to a 
user-defined constant. 


User Action. Remove the assignment statement; once you have 
assigned a value to a declared constant, you cannot change it. 


CONNOTALL, constant <name> _ not allowed in assignment context 


Explanation. ERROR - The program tries to assign a value to a 
user-defined constant. 


User Action. Remove the assignment statement; once you have 
assigned a value to a declared constant, you cannot change it. 


COOMUSBE, coordinates must be within NDC space (0.0 to 1.0) 


Explanation. ERROR - The value of a coordinate is either less 
than 0.0 or greater than 1.0. 


User Action. Supply a value between 0.0 and 1.0. 


CORSTAFRA, corrupted stack frame 


Explanation. ERROR - An immediate mode statement was 
entered after a STOP statement was executed in the BASIC 
environment and something corrupted the stack. 


User Action. Check program logic to make sure that all array 
references are within array bounds. This error can also be 
caused by loading non-BASIC object modules in the BASIC 
environment. 
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COUONLALO, COUNT clause only allowed with array LIST clause 


Explanation. ERROR - A COUNT clause was found on a SET 
INITIAL CHOICE statement that contains a LIST clause that 
does not contain a string array. 


User Action. Remove the COUNT clause or use the array form 
of the LIST clause. 


COUVALCAN, COUNT value cannot be greater than array size 


Explanation. ERROR - In the COUNT clause, you specified a 
count that is larger than the size of the array that you supplied. 


User Action. Change either the COUNT value or the size of 
the array so that COUNT is less than or equal to the number of 
elements in the array. 


DATTYPEXP, data type required for variable <name> with /EXPLICIT 


Explanation. ERROR - A program compiled with the 
/TYPE=EXPLICIT qualifier declares a variable without specifying 
a data type. 


User Action. Supply a data type keyword for the variable or 
compile the program without the /TYPE=EXPLICIT qualifier. 


DATTYPNOT, data type keyword not allowed in SUB statement 


Explanation. ERROR - A SUB statement contains a data type 
keyword between the subprogram name and the parameter list. 


User Action. Remove the data type keyword. In a SUB state- 
ment, data type keywords can appear only within the parameter 
list. 


DATTYPREQ, data type required in EXTERNAL CONSTANT declaration 


Explanation. ERROR - An EXTERNAL CONSTANT statement 
has no data type keyword. 


User Action. Supply a data type keyword to specify the data 
type of the external constant. 


A-22 Compile-Time Error Messages 


DECIMERR, DECIMAL overflow 


Explanation. WARNING - The program contains a DECIMAL 
expression whose value is outside the valid range. 


User Action. Reduce the value of the DECIMAL expression. 


DECLEXSYN, DECLARED lexical function syntax error 


Explanation. ERROR - The syntax of the %DECLARED lexical 
function is specified incorrectly. 


User Action. Supply the correct syntax. 


DECPREOUT, DECIMAL precision specification out of range 


Explanation. ERROR - In the declaration for a packed decimal 
variable or constant, the number of digits to the right of the 
decimal point is greater than the total number of digits specified, 
or greater than 31. 


User Action. Change the declaration so that the total number 
of digits specified is less than 31, and the number of digits to 
the right of the decimal point is less than or equal to the total 
number of digits. 


DECSIZOUT, DECIMAL size specification out of range 


Explanation. ERROR - The declaration for a packed decimal 
variable or variable specifies more than 31 digits. 


User Action. Change the declaration to specify 31 or fewer 
digits. 
DEFINVNOT, DEF invocation not allowed in assignment context 


Explanation. ERROR - A DEF function invocation (including 
a parameter list) appears on the left side of an assignment 
statement. 


User Action. Remove the assignment statement. You cannot 
assign values to a function invocation. 
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DEFMODNOT, DEF <name> mode not as declared 


Explanation. ERROR - The specified data type in a function 
declaration disagrees with the data type specified in the function 
definition. 


User Action. Make the data type specifications match in both 
the function declaration and the function definition. 


DEFNOTDEF, DEF <name> not defined 


Explanation. ERROR - The program contains a reference to a 
nonexistent user-defined function. 


User Action. Define the function in a DEF statement. 


DEFNOTWHE, DEF not allowed in WHEN block or handler 


Explanation. ERROR - A DEF function definition is not allowed 
in a WHEN block or its associated handler. 


User Action. Remove the DEF function definition from within 
the WHEN block or handler. 


DEFRESREF, DEF <name> result reference illegal in this context 


Explanation. ERROR - The program attempts to assign a value 
to a DEF name outside the DEF block. 


User Action. Remove the assignment statement. You cannot 
assign a value to a DEF outside of the DEF block. 


DEFSIZNOT, DEF <name> decimal size not as declared 


Explanation. ERROR - The DECIMAL(d;s) size specified in the 
DEF statement does not match the DECIMAL(d;s) used in the 
associated DECLARE DEF statement. 


User Action. Make the DECIMAL size specification agree in 
both the DECLARE DEF and DEF statements. 
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DEFSTAPAR, DEF* formal <formal-name> inconsistent with usage outside 


DEF* 


Explanation: ERROR - A DEF* formal parameter has the same 
name as a program variable, but different attributes. 


User Action: You should not use the same names for DEF* 
parameters or program variables. If you do, you must ensure 
that they have the same data type and size. 


DEFSTRPAR, DEF string parameter is illegal in MAP DYNAMIC or REMAP 


Explanation: ERROR - You cannot use a static string that is a 
parameter declared in a DEF or DEF* function as the storage area 
in a MAP DYNAMIC or REMAP statement. 


User Action: Change the storage area specification in the MAP 
DYNAMIC or REMAP statement to use either a MAP name or a 
static string variable that is not a parameter to the DEF or DEF* 
function. 


DELETE, ignoring <item> 


Explanation: ERROR - The program contains a syntax error. 
The compiler tries to recover from the error by ignoring an 
operator or separator in the source line. For example, 

DIM A(3, ) is a syntax error, but VAX BASIC continues the 
compilation by ignoring the comma. The compilation continues 
only in order to discover other errors; no object module is 
produced. 


User Action: Correct the syntax error in the displayed line. 


DEPNOTANS, /DEPENDENCY_DATA qualifier not allowed with /ANSI 
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Explanation: ERROR - The /DEPENDENCY_DATA qualifier 
conflicts with the /ANSI_STANDARD qualifier. 


User Action: Specify either the /DEPENDENCY_DATA qualifier 
or the /ANSI_STANDARD qualifier, but not both. 
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DESOUTRAN, destination out of range 


Explanation: FATAL - The branch destination in an ON GOSUB 
statement is greater than 32767 bytes away from the statement. 


User Action: Reduce the distance between the destination and 
the statement. 


DIMOUTRAN, dimension is out of range 


Explanation: ERROR - The program contains the declaration of 
an array that specifies a negative number as a dimension. 


User Action: Change the dimension to a positive number. 


DIMLSSZERO, dimension must be greater than zero 


Explanation: ERROR - The number specified for a dimension 
must be greater than zero. 


User Action: Change the number to be greater than zero. 


DIMTOOBIG, dimension for array <name> must be between 1 and 
<number> 


Explanation: ERROR - The number of the dimension specified is 
greater than the number of dimensions in the array. 


User Action: Change the dimension number to be less than or 
equal to the number of dimensions in the array. 


DIRMUSTBE, directive must be only item on line 


Explanation: ERROR - The program contains a compiler direc- 
tive that is not the only item on the line. 


User Action: Place the directive on its own line. 


DIRNOTIMM, directive not valid in immediate mode 


Explanation: ERROR - A compiler directive was typed in the 
BASIC environment. 


User Action: None. Compiler directives are invalid in immedi- 
ate mode. 
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DIVBY_ZER, division by zero 


Explanation: WARNING - The value of a number divided by 
zero is indeterminate. 


User Action: Change the expression so that no expression is 
divided by the constant zero. 


DRAWITREQ, DRAW WITH clause requires 4X4 matrix 


Explanation: ERROR - A user matrix is specified in a DRAW 
statement WITH clause where a 2 dimensional matrix with lower 
bounds 0 and upper bounds 4 in both dimensions is required. 


User Action: Declare the matrix to be a 2 dimensional matrix 
with lower bounds 0 and upper bounds 4 in both dimensions. 


DUPCLASPE, duplicate clause specified 


Explanation: ERROR - A duplicate clause was found on a SET 
INITIAL statement or a graphics input statement. 


User Action: Remove the duplicate clause. 
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DUPLINNOT, duplicate line numbers not ANSI 


Explanation. ERROR - A program compiled with the /ANSI_ 
STANDARD qualifier from the DCL command level, or called 
into the BASIC environment with the OLD command while the 
/ANSI_STANDARD qualifier is in effect, contains two identical 
line numbers. 


User Action. Remove one instance of the duplicate line num- 
ber. Even if you compile the program without the /ANSI_ 
STANDARD, VAX BASIC will ignore all statements connected 
with the first instance of the duplicate line number before 
compiling the program. 


DUPLNEND, duplicate line number <number> found 


Explanation. INFORMATION or WARNING 


Explanation. INFORMATION - A line number in an include file 
is the same as a line number in the main source file. 


Explanation. WARNING - There are two lines in the main 
source file with the same line number. VAX BASIC keeps the 
second occurrence of the line number. 


User Action. Correct the source by changing one of the line 
numbers to an unused number. 


DYNATTONL, DYNAMIC attribute only valid for MAP areas 


Explanation. ERROR - A COMMON keyword is followed by 
the DYNAMIC keyword. 


User Action. Remove the DYNAMIC keyword. The DYNAMIC 
attribute is valid only for MAP areas. 
DYNSTRINH, dynamic string variable <name> _ inhibits optimization 


Explanation. INFORMATION - This error is reported only when 
the /NOSETUP qualifier is in effect. The program contains 

a dynamic string variable. This prevents optimization of the 
compiler-generated code. 


User Action. Place the string variable in a COMMON or MAP. 
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ELSIMPCON, ELSE appears in improper context, ignored 


Explanation. ERROR - The program contains an ELSE clause 
that either is not preceded by an IF statement or that appears 
after an IF has been terminated with a line number or END IF, 


User Action. Remove either the ELSE clause or the terminating 
line number or END IF. 


ENDIMPCON, END IF appears in improper context, ignored 


Explanation. ERROR - The program contains an END IF state- 
ment that either is not preceded by an IF statement or occurs 
after an IF has been terminated by a line number. 


User Action. Supply an IF statement or remove the terminating 
line number. 


ENDSTAREQ, END statement required in ANSI 


Explanation. INFORMATION - A program compiled with 
the /ANSI_STANDARD qualifier does not contain an END 
statement. 


User Action. Include an END statement as the last statement in 
the program. ANSI Minimal BASIC requires an END statement. 


ENTARERFIE, entire array field of virtual record cannot be passed 


Explanation. ERROR - The program attempts to pass an entire 
array aS a parameter to a subprogram when: 1 the array is an 
item in a record and 2) the record is itself dimensioned as a 
virtual array. 


User Action. Assign the values of the array to another array that 
is of the same data type and dimension but that is not a field of a 
virtual array record, and pass the second array as the parameter. 


ENTARRNOT, entire array not allowed in this context 


Explanation. ERROR - The program specifies an entire array 
in a context that permits only array elements, for example, in a 
PRINT statement. 


User Action. Remove the reference to the entire array. 
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ENTGRONOT, entire GROUP or RECORD not allowed in this context 


Explanation. ERROR - The program specifies an entire GROUP 
or RECORD in a context that permits only GROUP or RECORD 
components, for example, PRINT ABC::XYZ where XYZ is a 
GROUP. 


User Action. Remove the reference to the entire GROUP or 
RECORD. 


ENTVIRARR, entire virtual array cannot be a parameter 


Explanation. ERROR - The program attempts to pass an entire 
virtual array as a parameter. 


User Action. None. You cannot pass an entire virtual array as a 
parameter. 


EOLNOTTER, End of line does not terminate IFs due to active blocks 


Explanation. ERROR - A THEN or ELSE clause contains a loop 
block, and a line number terminates the IF-THEN-ELSE before 
the end of the loop block. 


User Action. Make sure that any loop is entirely contained in 
the THEN or ELSE clause. 


ERLNOTALL, ERL statement not allowed in programs without line 
numbers 


Explanation. ERROR - An ERL statement has been found ina 
program without line numbers. 


User Action. Remove the ERL statement. 


ERRACCLIB, error accessing module <mod-name> in text library 
<text-lib-name> 


Explanation. ERROR - VAX BASIC found an unexpected 
LIBRARIAN error while trying to %INCLUDE a text library 
module. This error message is followed by a specific LIBRARIAN 
(LBR) message. 


User Action. Take appropriate action based on the associated 
LBR message. 
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ERRCLOLIB, error closing text library <text-lib-name> 


Explanation. ERROR - The text library specified in an 
%INCLUDE directive could not be closed. This error message is 
followed by the specific LIBRARIAN (LBR) error. 


User Action. Take appropriate action based on the associated 
LBR message. 


ERROPEFIL, error opening file 


Explanation. ERROR - The file specified in a %INCLUDE 
directive could not be opened. This error message is followed by 
the specific RMS error. 


User Action. Take appropriate action based on the associated 
RMS error. 


ERROPELIB, error opening text library <text-lib-name> 


Explanation. ERROR - The text library specified in an 
%INCLUDE directive could not be opened. This error message 
is followed by the specific LIBRARIAN (LBR) error. 


User Action. Take appropriate action based on the associated 
LBR message. 


ERRRECCOM, erroneous RECORD component 


Explanation. ERROR - The program contains an erroneous 
record component, for example, specifying A::B when RECORD 
A has no component named B. 


User Action. Remove the erroneous reference. 


EXEDIMILL, executable DIMENSION illegal for static array 


Explanation. ERROR - A DIMENSION statement names an 
array already declared with a DECLARE, COMMON, MAP, 
or RECORD statement, or one that was declared statically in a 
previous DIMENSION statement. 


User Action. Remove the executable DIMENSION statement 
or originally declare the array as executable in a DIMENSION 
statement. 
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EXPDECREQ, explicit declaration of <name> required 


Explanation: ERROR - The program is compiled with the 
/TYPE:EXPLICIT qualifier in effect, and the program references 
a variable, constant, function, or subprogram name that is not 
explicitly declared. 


User Action: Explicitly declare the variable, constant, function, 
or subprogram. 


EXPIFDIR, expecting IF directive 


Explanation: ERROR - The program contains a %END that is 
not immediately followed by a %IF. 


User Action: Supply a %IF immediately following the %END. 


EXPNOTALL, expression not allowed in this context 


Explanation: ERROR - The program contains an expression in 
a context that allows only simple variables, array elements or 
entire arrays, for example, in FIELD and MOVE statements. 


User Action: Remove the expression. 


EXPTOOCOM, expression too complicated 


Explanation: ERROR - The program contains an expression or 
statement too complicated to compile. This message can occur 
whenever VAX BASIC is unable to allocate sufficient registers. 


User Action: Recode as required; for example, rewrite the 
statement as two or more less complicated statements. 


EXPUNAOPE, expecting unary operator or legal lexical operand 


Explanation: ERROR - A compiler directive contains an invalid 
lexical expression, for example, %IF *3% %THEN. 


User Action: Correct the lexical expression. 


EXTELSFOU, extra ELSE directive found 


Explanation:: ERROR - The program contains a %ELSE directive 
that is not matched with a %IF directive. 


User Action: Make sure that each %ELSE is preceded by a %lIF, 
and that each %IF contains no more than one %ELSE clause. 
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EXTENDIF, extra END IF directive found 


Explanation: ERROR - A program unit contains a %END %IF 
without a preceding %IF directive. 


User Action: Supply a %IF for the %END %IF. 


EXTLEFPAR, extra left parenthesis in expression 


Explanation: ERROR - A compiler directive contains a lexical 
expression with an extra left parenthesis. 


User Action: Remove the extra parenthesis. 


EXTNAMTOO, EXTERNAL name too long, truncating to <new-name> 


Explanation: WARNING - An EXTERNAL statement names a 
symbol longer than 31 characters. 


User Action: Shorten the symbol name to 31 characters or less. 


EXTRIGPAR, extra right parenthesis in expression. 


Explanation: ERROR - A compiler directive contains a lexical 
expression with an extra right parenthesis. 


User Action: Remove the extra parenthesis. 


EXTSTRVAR, EXTERNAL STRING variables not supported 


Explanation: ERROR - The program contains an EXTERNAL 
statement that specifies an external string variable. 


User Action: Remove or change the EXTERNAL statement. 
VAX BASIC does not support external string variables. 


FEANOTANS, language feature not ANSI 


Explanation: INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains a VAX BASIC feature 
(such as a long variable name or a string array) that does not 
conform to the ANSI Minimal BASIC Standard. (See Chapter 7 
for more information on the ANSI Minimal Standard.) 


User Action: Although VAX BASIC allows you to run programs 
with non-ANSI language features, you must remove these 
features if you want your program to be transportable to other 
ANSI Minimal BASIC compilers. 
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FIEVALONL, FIELD valid only for dynamic string variables 


Explanation. ERROR - A FIELD statement contains a numeric or 
fixed-length string variable. 


User Action. Remove the numeric or fixed-length string variable. 
Only dynamic string variables are valid in FIELD statements. 


FILACCERR, file access error for INCLUDE directive <file-name> 


Explanation. ERROR - The file named in the %INCLUDE 
directive was correctly opened but could not be read for some 
reason, for example, the disk drive was switched off line. 


User Action. Take action based on the associated RMS error 
messages. 


FILEWRITE, <prog-name> written to file: <file-name> 


Explanation. INFORMATION - The specified program name has 
been saved in file-name. 


User Action. None. 


FILNOTALL, FILL not allowed in MAP DYNAMIC 


Explanation. ERROR - A MAP DYNAMIC statement contains a 
FILL item. 


User Action. Remove the FILL item. 


FILNOTDEL, error deleting <file-name> 


Explanation. ERROR - An error was detected in attempting to 
delete a file. 


User Action. Supply a valid file specification, or take corrective 
action based on the associated message. 


FILTOOBIG, FILL number <n> in overlay <m> of MAP <name> 
too big 


Explanation. ERROR - A FILL string length or repeat count 
caused the compiler to try to allocate more than 2°31 longwords 
of storage. 


User Action. Check the specified MAP statement and change 
the FILL string length or repeat count. 
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FLOCVTILL, floating CVT valid only for SINGLE and DOUBLE 


Explanation. ERROR - A CVTF$ or CVT$F function names a 
GFLOAT or HFLOAT value as an argument. 


User Action. Use a SINGLE or DOUBLE argument rather than 
GFLOAT or HFLOAT. 


FLOPOIERR, floating point error or overflow 


Explanation. WARNING - The program contains a numeric 
expression whose value is outside the valid range for the default 
floating-point data type. 


User Action. Modify the expression so that its value is within 
the allowable range or select as the default REAL size a floating- 
point data type that has a greater range. 


FNEWHINOT, exit from DEF while not in DEF 


Explanation. ERROR - An FNEXIT or EXIT DEF statement has 
no preceding DEF statement. 


User Action. Define the function before inserting an FNEXIT or 
EXIT DEF statement. 


FNEWITDEF, end of DEF seen while not in DEF 


Explanation. ERROR - An FNEND or END DEF statement has 
no preceding DEF statement. 


User Action. Define the function before inserting an FNEND 
statement or delete the FNEND statement. 


FORFEEMUS, FORM FEED must appear at end of line 


Explanation. INFORMATION - A form feed character is fol- 
lowed by other characters in the same line. 


User Action. Remove the characters following the form feed. A 
form feed must be the last or only character on a line. 


FORPARMUS, formal parameter must be supplied for <name> 


Explanation. ERROR - The declaration of a DEF, SUB, or 
FUNCTION routine contains the parentheses for a parameter list 
but no parameters. 


User Action. Supply a parameter list or remove the parentheses. 
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FORSTRPAR, formal string parameters may not be FIELDed 


Explanation. ERROR - A variable name appears both in a 
subprogram formal parameter list and a FIELD statement in the 
subprogram. 


User Action. Remove the variable from FIELD statement or the 
parameter list. 


FOUENDWIT, found end of <block> without matching <item> 


Explanation. ERROR - The program contains an END SELECT, 
END DEF, END FUNCTION, FUNCTIONEND, SUBEND, 
END SUB, or END IF without a matching SELECT, DEF, SUB, 
FUNCTION or IF. 


User Action. Supply a SELECT, DEF, FUNCTION, SUB, or IF to 
match the END <block> statement, or remove the erroneous 
END statement. 


FOUND, found <item> when expecting <item> 


Explanation. ERROR - The program contains a syntax error. 
VAX BASIC displays the item where the error was detected, then 
displays one or more items that make more sense in that context. 
The compilation continues so that other errors may be detected. 
The actual program line remains unchanged and no object file is 
produced. 


User Action. Examine the line carefully to discover the error. 
Change the program line to correct the syntax error. 


FOUNXTWIT, found NEXT without matching WHILE or UNTIL 


Explanation. ERROR - The program contains a NEXT statement 
without a corresponding WHILE or UNTIL statement. 


User Action. Supply a WHILE or UNTIL statement or remove 
the erroneous NEXT statement. 


FOUWITMAT, found NEXT without matching FOR 


Explanation. ERROR - The program contains a NEXT <control- 
variable> statement without a matching FOR <control- 
variable> statement. 


User Action. Supply a FOR statement or remove the erroneous 
NEXT statement. 
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FUNINVNOT, function invocation not allowed in assignment context 


Explanation. ERROR - An external function invocation (includ- 
ing a parameter list) appears on the left side of an assignment 
statement. 


User Action. Remove the assignment statement. You cannot 
assign values to a function invocation. 


FUNNESTOO, function nested too deep 


Explanation. ERROR - The program contains too many levels of 
function definitions within function definitions. 


User Action. Reduce the number of nested functions. 


FUNWHINOT, exit from FUNCTION while not in FUNCTION 


Explanation. ERROR - An EXIT FUNCTION or FUNCTIONEXIT 
statement was found in a module that is not a FUNCTION 
subprogram. 


User Action. Remove the EXIT FUNCTION or FUNCTIONEXIT 
statement. 


GRAARRMUS, graphics array must be integer or real 


Explanation. ERROR - The specified array has a data type other 
than an integer or real data type. 


User Action. Declare the array with an integer or real data type. 


HANNOTDEF, HANDLER not allowed in DEF 


Explanation. ERROR - A HANDLER definition has been found 
within a DEF function definition. 


User Action. Remove the HANDLER definition from inside the 
DEF function definition. 
HANNOTFOU, error handler <name> _ not found 


Explanation. ERROR - You did not define the HANDLER you 
referenced in a WHEN statement. 


User Action. Define the HANDLER you reference in the WHEN 
statement. 
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HANNOTWHE, HANDLER not allowed in a WHEN block or handler 


Explanation: ERROR - A detached HANDLER definition was 
found in a WHEN block protected region or associated handler. 


User Action: Remove the HANDLER definition from within all 
WHEN block protected regions and associated handlers. 


HANWHINOT, exit from HANDLER while not in HANDLER 


Explanation: ERROR - An EXIT HANDLER statement was 
found while not in a HANDLER block. 


User Action: Remove the EXIT HANDLER statement. 


HORJUSMUS, horizontal justification must be “LEFT”, “CENTER”, “RIGHT” or 
“NORMAL” 


Explanation: ERROR - You specified an invalid value for the 
horizontal component of the SET TEXT JUSTIFY statement. 


User Action: Specify one of the values listed in the message. 


IDEMAYAPP, IDENT directive may appear only once per module 


Explanation: WARNING - The program contains more than one 
%IDENT compiler directive. 


User Action: Remove all but one %IDENT directive. 


IDENAMTOO, IDENT directive name is too long 


Explanation: WARNING - The quoted string in a % IDENT 
directive is too long. 


User Action: Reduce the length of the string. The maximum 
length is 31 characters. 


IF_EXPMUS, IF directive expression must be terminated by THEN directive 


Explanation: ERROR - A %IF directive contains a %ELSE clause 
with no intervening %THEN clause. 


User Action: Insert a % THEN clause. 


Compile-Time Error Messages A-37 


IF_IN_INC, IF directive in INCLUDE directive needs END IF directive in same 
file 


Explanation: ERROR - A %INCLUDE file contains a %IF but no 
%END %IF. 


User Action: Supply a %END %IF for the %INCLUDE file. 


IF_NOTTER, IF statement not terminated 


Explanation: ERROR - The program contains an IF-THEN-ELSE 
statement within a block (for example, a FOR-NEXT, SELECT- 
CASE, or WHILE block) and the end of the block was reached 
before the IF-THEN-ELSE statement was terminated. 


User Action: Check program logic to be sure IF-THEN-ELSE 
statements are terminated with a line number or an END IF 
statement before the end of the block is reached. 


ILLALLCLA, illegal ALLOW clause <clause> 


Explanation: ERROR - The program contains an ALLOW clause 
on a GET statement, and the file was not opened with the 
UNLOCK EXPLICIT clause. 


User Action: Either remove the ALLOW clause from the GET 
statement or use the UNLOCK EXPLICIT clause in the OPEN 
statement. 


ILLARGBP2, illegal argument count for BP2 


Explanation: INFORMATION - The program contains a 
SUB, DEF or EXTERNAL FUNCTION reference with more 
than 32 parameters. This error is reported only when the 
/FLAG:BP2COMPATIBILITY qualifier is in effect. 


User Action: If the program must run under both VAX BASIC 
and PDP-11 BASIC-PLUS-2, the function must have 32 or fewer 
parameters. 


ILLARGPAS, illegal argument passing mechanism 


Explanation: ERROR - The program specifies an invalid 
argument-passing mechanism. For example, passing strings 
or arrays BY VALUE, or passing an entire virtual array. 


User Action: Check all elements for proper parameter-passing 
mechanism. 
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ILLCALFUN, illegal CALL of a DECIMAL, HFLOAT or STRING function 


Explanation. ERROR - You attempted to use the CALL state- 
ment to invoke either a DECIMAL, HFLOAT, or STRING 
function. 


User Action. Invoke the function not using the CALL statement. 


ILLCHA, illegal character <ASCII code> 


Explanation. WARNING - The program contains illegal or 
incorrect characters. 


User Action. Examine the program for correct usage of the VAX 
BASIC character set and possibly delete the character. 


ILLCHAEXT, illegal character <ASCII code> in external name 


Explanation. ERROR - The external symbol in an EXTERNAL 
FUNCTION or CONSTANT declaration contains an invalid 
character. 


User Action. Remove the invalid character. External names can 
use Only printable ASCII characters: ASCII values in the range 
32 to 126, inclusive. 


ILLCHAIDE, illegal character <ASCII value> in IDENT directive 


Explanation. WARNING - A %IDENT directive contains an 
illegal character with the reported ASCII value. 


User Action. Remove the illegal character. 
ILLCONTYP, illegal constant type 


Explanation. ERROR - The program contains an invalid declara- 
tion, for example, DECLARE RFA CONSTANT. 


User Action. Remove the invalid data type. You cannot declare 
constants of the RFA data type. 
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ILLEXTPDP, <name> is illegal as a PDP-11 external name 


Explanation. INFORMATION - This error is reported only 
when the /FLAG:BP2COMPATIBILITY qualifier is in effect. 
The external name is longer than six characters or contains a 
non-RAD50 character. 


User Action. Reduce the length of the name or remove the 
non-RAD50 character. 


ILLFRMNAM,, illegally formed name 


Explanation. ERROR - The program contains an invalid user 
identifier (such as a variable, constant or function name). 


User Action. Change the name to comply with the rules for 
naming user identifiers. See the VAX BASIC Reference Manual for 
more information. 


ILLFRMNUM, illegally formed numeric constant 


Explanation. ERROR - The program contains either: 1) an 
invalid E-format expression or 2) a numeric constant with a 
digit that is invalid in the specified radix, for example, a decimal 
constant containing a hexadecimal digit. 


User Action. Supply a valid E-format expression or a constant 
that is valid in the specified radix. 


ILLGOTO, can’t GOTO outside current procedure 


Explanation. WARNING - The target line number of an imme- 
diate mode GOTO statement is outside of the currently compiled 
procedure. 


User Action. None. If you RUN a source file containing more 
than one program unit, the currently compiled program is the last 
program unit in the source file. If you use the OLD command 
to read a program into memory and load one or more object 
modules, then type RUN, the currently compiled procedure is 
the program you read into memory with OLD. 
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ILLIDEPDP, illegal %IDENT string for PDP-11 


Explanation. INFORMATION - A %IDENT compiler directive 
contains a string that is invalid for PDP-11 systems. This error is 
issued only when the BP2 compatibility flagger is enabled. 


User Action. Change the %IDENT string. The string must be 
between 1 and 6 characters, and must contain only RAD-50 
characters. 


ILLIO_CHA, illegal I/O channel 


Explanation. ERROR - A constant channel expression is greater 
than 99, or a variable channel expression is greater than 119. 


User Action. If the channel expression is a constant, change to 
be less than or equal to 99. A variable channel expression can 
be less than or equal to 119; however, channels in the range 100 
through 119 are reserved for programs using LIB$}GET_LUN. 


ILLLINNUM, illegal line number in CHAIN 


Explanation. ERROR - A CHAIN with LINE statement specifies 
an invalid line number. Either the number is outside the valid 
range, or a string expression follows the LINE keyword. 


User Action. Supply an integer line number between 1 and 
32767, inclusive. 


ILLLOCARG, illegal LOC argument 


Explanation. ERROR - An argument to the LOC function is a 
constant, virtual array element, or expression. 


User Action. Change the argument to the LOC function. 


ILLLOONES, illegal loop nesting, expecting NEXT <variable> 
Explanation. ERROR - The program contains overlapping loops. 


User Action. Examine the program logic to make sure that the 
FOR and NEXT statements for the inside loop lie entirely within 
the outside loop. 
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ILLMATOPE, illegal matrix operation 


Explanation. ERROR - The program attempts matrix division. 
The operation is treated as a MAT multiply, and the compilation 
continues. 


User Action. Remove the attempted matrix division. VAX 
BASIC does not support this operation. 
ILLMCHPDP, illegal passing mechanism on PDP-11s 


Explanation. INFORMATION - This error is reported only 
when the /FLAG:BP2COMPATIBILITY qualifier is in effect. A 
parameter list contains a BY clause that is invalid in PDP-11 
BASIC-PLUS-2, for example, specifying BY DESC for parameters 
that are not entire arrays or strings. 


User Action. See the VAX BASIC Reference Manual for allowable 
BASIC-PLUS-2 parameter-passing mechanisms. 


ILLMIDLEN, illegal MID assignment length 


Explanation. ERROR - The value of the length in the MID 
statement is either greater than the length of the string or less 
than or equal to zero. 


User Action. Correct the length to be between 1 and the length 
of the string. 


ILLMIDSTRT, illegal MID starting value 


Explanation. ERROR - The starting value in the MID statement 
is less than or equal to zero. 


User Action. Correct the starting value to be greater than or 
equal to one. 


ILLMODMIX, illegal mode mixing 


Explanation. ERROR - The program contains string and numeric 
operands in the same operation. 


User Action. Change the expression so that it contains either 
string or numeric operands, but not both. 
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ILLMULDEF, illegal multiple definition of name <name> 
Explanation. ERROR - The program uses the same name for: 
¢ More than one variable 
e A variable and a MAP 


e A variable and a COMMON 
e A MAP and COMMON 


User Action. Use unique names for variables, COMMONSs and 
MAPs. 


ILLMULOPT, OPTIONAL cannot be specified more than once 


Explanation. ERROR - The OPTIONAL clause was specified 
more than once in the EXTERNAL statement for a single SUB 
or FUNCTION. This is not allowed because OPTIONAL implies 
that all parameters following it are optional. 


User Action. Fix the EXTERNAL statement so that it has at most 
1 OPTIONAL clause per SUB or FUNCTION. 


ILLNESDEF, illegally nested DEFs 


Explanation. ERROR - The program contains a DEF function 
block within another DEF function block. 


User Action. Remove the inner DEF block. A DEF cannot 
contain another DEF. 
ILLOPEARG, illegal operation for argument 


Explanation. ERROR - The program performs an operation that 
is inconsistent with the data type of the arguments, for example, 
an arithmetic operation on variables of the RFA data type. 


User Action. Remove the operation or change the data type of 
the arguments. 


ILLOPTBAS, illegal OPTION BASE value 


Explanation. INFORMATION - A program compiled with 
the /ANSI_STANDARD qualifier contains an OPTION BASE 
statement that specifies a value other than 0 or 1. 


User Action. Change the OPTION BASE statement to specify 
either 0 or 1. 
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ILLQUACOM,, illegal qualifier combination 


Explanation. ERROR - In the BASIC environment, you 
specified an illegal combination of qualifiers, such as 
COMPILE/NOSHOW=CDD. 


User Action. Issue the command again, using a valid combina- 
tion of qualifiers. 


ILLSTROPE, illegal string operator 


Explanation. ERROR - The program specifies an invalid string 
operation; for example, A$ = B$ - C$. 


User Action. Replace the invalid operator. 


ILLUSAFIE, illegal usage of FIELDed variable 


Explanation. A MAT statement operates on an element of a 
string array that appears in a FIELD statement. 


User Action. Remove the array from the MAT statement. 


ILLUSEUNA, illegal use of unary operator 


Explanation. ERROR - A compiler directive contains an invalid 
lexical expression, for example, %IF 1 NOT 2. 


User Action. Correct the invalid lexical expression. 


ILLWAIVAL, WAIT value must be in the range 0 to 255 inclusive 


Explanation. ERROR - An integer expression was specified on a 
WAIT clause that is less than 0 or greater than 255. 


User Action. Specify an integer expression from 0 through 255. 


IMMMODOPE, immediate mode operation requires storage allocation 


Explanation. ERROR - An immediate mode statement attempted 
to allocate storage, for example, to create a new variable. 


User Action. None. You cannot create new storage in immediate 
mode. 
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IMMNOTANS, immediate mode not valid when ANSI 


Explanation. ERROR - An immediate mode statement was typed 
when in ANSI mode. 


User Action. None. 


IMPCNTNOT, implied continuation not allowed 


Explanation. ERROR - The program contains an implied con- 
tinuation line after a statement that does not allow implicit 
continuation, for example, a DATA statement. 


User Action. Use an ampersand (&) to continue the statement. 


IMPDECILL, implicit declaration of <name> _ illegal in immediate mode 


Explanation. ERROR - A new variable was named in an imme- 
diate mode statement after a STOP, for example, PRINT B after a 
STOP in a program that has no variable named B. 


User Action. None. You cannot create new variables in immedi- 
ate mode after a STOP statement. 


IMPDECNOT implied declaration not allowed for <name> with 
/EXPLICIT 


Explanation. ERROR - A program compiled with the 
/TYPE=EXPLICIT qualifier contains an implicitly declared 
variable. 


User Action. Declare the variable explicitly or compile the 
program without the /TYPE=EXPLICIT qualifier. 


INACODFOL, inaccessible code follows line <n> statement <m> 


Explanation. WARNING - The program contains one or more 
statements that cannot be accessed, for example, a multi- 
statement line whose first statement is a GOTO, EXIT, ITERATE, 
RESUME, or RETURN. 


User Action. Make sure that these statements are the only 
statements on the line, or the last statement on a multi-statement 
line. 
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INCDIRSYN, INCLUDE directive syntax error 


Explanation. ERROR - A %INCLUDE directive either is not 
followed by a quoted string or incorrectly uses the % FROM 
%CDD or %FROM %LIBRARY clause. 


User Action. Supply either a quoted string or the correct syntax 
for the %FROM %CDD or %FROM %LIBRARY clause. 


INCFUNUSA, inconsistent function usage for function <name> 


Explanation. ERROR - The parameter list in a DEF function 
invocation contains a string where the function expected a 
number, or vice versa. This message is issued only when the 
invocation occurs before the DEF statement in the program. 


User Action. Supply a correct parameter in the function invoca- 
tion or correct the parameter list in the DEF. 


INCRMSERR, INCLUDE directive RMS error number <number> 


Explanation. ERROR - A %INCLUDE directive caused an RMS 
error when accessing the specified file. 


User Action. Take action based on the reported RMS error 
number. 


INCSUBUSE, inconsistent subscript use for <array-name> 


Explanation. ERROR - The number of subscripts in an array 
reference does not match the number of subscripts specified 
when the array was created. 


User Action. Specify the same number of subscripts. 


INIOUTRAN, initial value must be within the specified range 


Explanation. ERROR - The specified initial value is not within 
the range specified in the RANGE clause. 


User Action. Change either the initial value or the range values 
so that the initial value falls within the range. 
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INPPROMUS, input prompt must be a string constant 


Explanation. ERROR - An INPUT, LINPUT, or INPUT LINE 
statement list contains a numeric constant immediately following 
the statement. 


User Action. Remove the numeric constant. You can specify 
only a string constant immediately after an INPUT, LINPUT, or 
INPUT LINE statement. 


INSERTB, assuming <keyword> before <keyword> 


Explanation. ERROR - The program contains a syntax error. 
VAX BASIC assumes a keyword is missing and continues com- 
pilation under that assumption so that other errors may be 
detected. The actual program line remains unchanged and no 
object file is produced. 


User Action. Examine the line carefully to discover the error. 
Change the program line to correct the syntax error. 


INSERTM, assuming <keyword> to match <keyword> 


Explanation. ERROR - The program contains a syntax error. 
VAX BASIC assumes a keyword is misspelled and continues 
compilation under that assumption so that other errors may be 
detected. The actual program line remains unchanged and no 
object file is produced. 


User Action. Examine the line carefully to discover the error. 
Change the program line to correct the syntax error. 

INSSPADYN, insufficient space for MAP DYNAMIC variable in MAP 
<name> 


Explanation. ERROR - A variable named in a MAP DYNAMIC 
statement is larger than the MAP. For example, an HFLOAT 
variable in a MAP that is only four bytes long. 


User Action. Increase the size of the MAP so that it is large 
enough to hold the largest member. 
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INTCODERR, an internal coding error has been detected. Submit an SPR. 


Explanation. ERROR - An error has been detected in the VAX 
BASIC compiler. 


User Action. Please submit an SPR with the source code of a 
small program that produces this error. 


INTCONEXC, integer constant exceeds machine integer size 


Explanation. ERROR - The value specified in a DECLARE 
CONSTANT statement exceeds the largest allowable value for an 
integer. The maximum is 2147483647. 


User Action. Supply a value in the valid range. 


INTCONREQ, integer constant required 


Explanation. ERROR - The program contains a noninteger 
named constant in a context that requires an integer. For 
example: 


DIM A ('123'D) 


User Action. Supply an integer constant. 


INTDATTYP, integer data type not supported in ANSI 


Explanation. ERROR - A program compiled with the /ANSI_ 
STANDARD qualifier contains an integer variable or array. 


User Action. Remove the integer variable or array. 


INTERR, integer error or overflow 


Explanation. WARNING - The program contains an integer 
expression whose value is outside the valid range. 


User Action. Modify the expression so that its value is within 
the allowable range or use an integer data type that can contain 
all possible values for the expression. 


INVCHNNUM, invalid channel number, must be greater than zero 


Explanation. ERROR - A channel number less than or equal to 
zero was specified. 


User Action. Change the channel number to be greater than 
zero. 
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INVCONREQ, invalid conversion requested 


Explanation. ERROR - The program contains a reference to the 
REAL or INTEGER functions and the argument is an entire array, 
GROUP, RECORD, or RFA expression. 


User Action. Remove the invalid argument. The argument to 
these functions must be a numeric expression. 


INVINTTYP, invalid integer type 


Explanation. ERROR - A reference to the INTEGER function 
contains an invalid data type keyword, for example, 
A = INTEGER(A, SINGLE). 


User Action. Change the invalid data type keyword. The 
INTEGER function returns only BYTE, WORD, or LONG values. 
INVLOGNAM, invalid logical name 


Explanation. ERROR - The argument to the ASSIGN compiler 
command specified a logical name length of less than 1 or greater 
than 63. 


User Action. Supply a valid logical name. 


INVPRISPE, invalid priority specification, expecting < or > 


Explanation. ERROR - On the SET INPUT PRIORITY statement, 
you specified a character other than < or > to indicate the 
relative priorities of the two transformation numbers. 


User Action. Specify the priority relationship with less than < 
(lower priority) or greater than > (higher priority). 
INVREATYP, invalid real type 


Explanation. ERROR - A reference to the REAL function con- 
tains an invalid data type keyword, for example, A = REAL(A, 
LONG). 


User Action. Change the invalid data type keyword. The REAL 
function returns only SINGLE, DOUBLE, GFLOAT, or HFLOAT 
values. 
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INVSUBTYP, <data-type> is not a subtype of <data-type> 


Explanation. ERROR - The program contains an invalid decla- 
ration containing contradictory type declarations, for example, 
DECLARE REAL BYTE. 


User Action. Supply a valid declaration. Use only valid integer 
subtypes for INTEGER and only valid floating-point subtypes for 
REAL. 


IS_NOTDYN, <name> is not a DYNAMIC MAP variable of MAP 
<name> 


Explanation. ERROR - A REMAP statement names a variable 
that was not named in the MAP DYNAMIC statement for that 
MAP. 


User Action. Remove the variable from the REMAP statement 
or name the variable in the MAP DYNAMIC statement for that 
map. 


ITEMUSAPP, ITERATE must appear within a loop 


Explanation. ERROR - The program contains an ITERATE 
statement that is not within a FOR-NEXT, WHILE, or UNTIL 
loop. 


User Action. Remove the ITERATE statement, or surround it 
with a loop. 


JMPBADBLO, jump to line number <line number> is into a controlled 
block 


Explanation. ERROR - The program attempts to transfer control 
to a WHEN block or associated handler. 


User Action. Change the program logic so that it does not 
transfer control to a WHEN block or associated handler. 


JMPBADLAB, jump to label: <Jabel> is into a block 


Explanation. ERROR - The program attempted to transfer 
control into a FOR-NEXT, WHILE, UNTIL, IF or SELECT-CASE 
block. 


User Action. Change the program logic so that it does not 
transfer control into a block. 
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JMPBADLIN, jump to line number <number> is into a block 


Explanation. INFORMATION - The program transfers control 
to a line number within a FOR-NEXT, WHILE, UNTIL, IF or 
SELECT-CASE block. 


User Action. This is an informational message. However, it is 
bad programming practice to transfer control into a block. 


JMPINTDEF, jump into DEF 


Explanation. ERROR - The program attempts to transfer control 
into a DEF block. 


User Action. Change the control statement; you cannot transfer 
control into a DEF block except by invoking the function. 


JMPOUTDEF, jump out of DEF 


Explanation. ERROR - The program attempts to transfer control 
out of a DEF block. 


User Action. Change the control statement. Use an EXIT DEF, 
FNEXIT, FNEND, or END DEF statement to transfer control out 
of a DEF block. 


JMPOUTHAN, jump out of HANDLER 


Explanation. ERROR - The program attempts to transfer control 
out of an error handler. 


User Action. Change the control statement. Use an EXIT 
HANDLER, RETRY, or CONTINUE statement to transfer control 
out of an error handler. 


JMPOUTPRO, jump out of program unit 


Explanation. ERROR - In a source file containing more than one 
program module, a statement attempts to transfer control from 
one module into another. 


User Action. Change the statement that attempts to transfer 
control; you cannot transfer control into a different program 
module. 
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JMPUNRLIN, jump to unreferenceable line number <number> 


Explanation. ERROR - A RESUME, GOSUB, or GOTO state- 
ment attempts to transfer control to a CASE statement. 


User Action. Label or number the SELECT statement and 
transfer control to the beginning of the SELECT-CASE block. 


KEYCANNOT, key <name> in MAP <map-name> cannot bea 
dynamic variable 


Explanation. ERROR - A KEY clause in an OPEN statement 
specifies a variable declared as dynamic in a MAP DYNAMIC 
statement. 


User Action. Specify a static variable in the KEY clause; that is, 
declare the variable in a MAP statement, not a MAP DYNAMIC 
statement. 


KEYIS_NEE, key is needed for indexed files 


Explanation. ERROR - The program attempts to open an in- 
dexed file for output, and the PRIMARY KEY clause is missing. 


User Action. Supply a PRIMARY KEY clause. 


KEYMUSBE, key must be either word, longword, string, decimal, record 
or group 


Explanation. ERROR - A FIND or GET statement on an in- 
dexed file contains a key specification that is not a WORD, 
LONG, STRING, DECIMAL, or an 8-byte RECORD or GROUP 
expression. 


User Action. Change the key specification to be a WORD, 
LONG, STRING, DECIMAL, or an 8-byte RECORD or GROUP 
expression. 


KEYMUSTBE, key, <vbl-name> in map <map-name> must be either 
word, longword, string, decimal, record or group 


Explanation. ERROR - An OPEN statement contains a key spec- 
ification that is not an unsubscripted WORD, LONG, STRING, 
DECIMAL, or an 8-byte RECORD or GROUP variable. 


User Action. Change the key specification to be an unsub- 
scripted WORD, LONG, STRING, DECIMAL, or an 8-byte 
RECORD or GROUP variable. 
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KEYNOTMAP, KEY <vbl-name> is not an unsubscripted variable in 
MAP <name> 


Explanation. ERROR - An indexed file OPEN statement specifies 
a KEY variable that does not appear in a MAP statement. 


User Action. Place the KEY variable in the MAP referenced by 
the OPEN statement’s MAP clause. 


KEYREQMAP, KEY clauses require a MAP clause 


Explanation. ERROR - An OPEN statement specifies KEY 
clauses without specifying a MAP clause. 


User Action. Supply a MAP clause to define the position of the 
keys in the record buffer. 

KEYSEGMUS, key segment <name> in map <map-name> must be a 
string key 


Explanation. ERROR - An OPEN statement specifies a seg- 
mented key containing a numeric variable. For example: 


OPEN “INDEX.DAT" AS FILE #1, ORGANIZATION INDEXED, & 
PRIMARY KEY (A$, B$, C%), MAP ABC 


User Action. Specify only string variables in segmented keys. 


KEYSINC, <keyword> keyword inconsistent with <keyword> 


Explanation. ERROR - An OPEN statement contains contradic- 
tory record format specifications, for example, both FIXED and 
VARIABLE. 


User Action. Specify only one record format. 


KEYTOOLON, KEY <name> in MAP <name> is too long (max is 
255) 


Explanation. ERROR - A KEY variable is longer than 255 
characters. 


User Action. Reduce the length of the KEY variable. The 
maximum key length is 255 characters. 
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KEYWORINC, keyword inconsistent with <OPEN clause> clause 


Explanation. ERROR - An OPEN statement contains an 
ALLOW, ACCESS, or RECORDTYPE clause whose keyword 
argument is invalid, for example, ACCESS FORTRAN. 


User Action. Change the clause argument to a valid keyword 
for that clause. 


LABNOTDEF, label <label> not defined 


Explanation. ERROR - The program tries to transfer control to a 
nonexistent label. 


User Action. Define the label before transferring control to it. 


LABNOTLAB, label <name> does not label an active block statement 


Explanation. ERROR - An EXIT statement in a loop, IF-THEN- 
ELSE or SELECT-CASE block specifies a label that does not refer 
to that block. 


User Action. Change the program so that the label actually 
refers to the block in which the EXIT statement occurs. 


LABNOTLOO, label <name> does not label an active loop statement 


Explanation. ERROR - In a loop, an EXIT or ITERATE statement 
specifies a label that does not refer to that loop. 


User Action. Change the program so that the label actually 
refers to the loop in which the EXIT or ITERATE statement 
occurs. 


LANFEADEC, language feature is declining 


Explanation. INFORMATION - The program contains a lan- 
guage feature that is not recommended for new program devel- 
opment, for example, the FIELD statement. This error is reported 
only when the /FLAG:DECLINING qualifier is in effect. 


User Action. Use: 1) MAP, MAP DYNAMIC and REMAP 
statements instead of FIELD, 2) EDIT$ rather than CVT$$, 3) and 
overlaid MAPs rather than CVTxx functions. 
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LANFEAINC, language feature incompatible with BASIC-PLUS-2 


Explanation: INFORMATION - The program contains syntax 
that results in different behavior under VAX BASIC and PDP-11 
BASIC-PLUS-2, for example, opening a terminal-format file. This 
error is reported only when the /FLAG:BP2COMPATIBILITY 
qualifier is in effect. 


User Action: None. 


LANFEAINH, language feature inhibits optimization 


Explanation: INFORMATION - A program compiled with the 
/NOSETUP qualifier contains a language feature that requires 
/SETUP, for example, the RESUME statement. The compilation 
continues with /SETUP in effect. 


User Action: None. The program must be compiled with 
/SETUP in effect for the language feature to work. 


LANFEANOT, language feature not available in BASIC-PLUS-2 


Explanation: INFORMATION - The program contains a lan- 
guage element that is not supported in BASIC-PLUS-2, for 
example, RECORD statements. This error is reported only when 
the /FLAG:BP2COMPATIBILITY qualifier is in effect. 


User Action: If the program must run under both VAX BASIC 
and PDP-11 BASIC-PLUS-2, you must remove the incompatible 
language feature. 


LANFEAOPE, language feature not available in VAX BASIC 


Explanation: ERROR - The program contains a PRINT statement 
with a RECORD clause. VAX BASIC does not support the 
RECORD clause. 


User Action: Remove the RECORD clause. 


LEFBOUSPE, left boundary must be less than the right boundary 


Explanation: ERROR - In a statement that specifies a viewport 
or windowsize, you specified a left boundary that is greater than 
or equal to the corresponding right boundary. 


User Action: Correct the left boundary so that it is less than the 
right boundary. 
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LENDYNSTER, string length not allowed on dynamic string <name> 


Explanation: ERROR - The program contains a dynamic string 
variable declaration that specifies a string length. 


User Action: Length specifications are allowed only for fixed- 
length strings; remove the length specification from the dynamic 
string, or allocate the string in a MAP or COMMON. 


LENNUMEFIL, string length not allowed on numeric FILL 


Explanation: ERROR - The program contains a numeric FILL 
item that specifies a length. 


User Action: Remove the length specification from the numeric 
FILL item. 


LETDIRSYN, LET directive syntax error 


Explanation: ERROR - A %LET directive contains a syntax error, 
for example, an invalid lexical identifier. 


User Action: Use the correct syntax for the %LET directive. 


LETKEYREQ, LET keyword required in ANSI 


Explanation: INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains an assignment statement 
that omits the LET keyword. 


User Action: Supply a LET keyword. 


LEXDIRSYN, lexical directive syntax error 


Explanation: ERROR - A syntax error was detected in a lexical 
directive. 


User Action: Correct the syntax of the lexical directive. 


LEXIDEMUS, lexical identifier must be declared before reference 


Explanation: ERROR - You reference a lexical identifier before 
you declare it. 


User Action: Declare the lexicial identifier before you reference 
it. 
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LINNOTALL, line numbers not allowed, use the EDIT command 


Explanation: ERROR - An EDIT command with a line number 
has been found in a program without line numbers. 


User Action: Use the EDIT command without specifying a line 
number to invoke a text editor. 
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LINNUMERR, illegal line number 


Explanation. ERROR - The program contains a line number that 
is outside the valid range or is not a valid integer (note that the 
per cent sign ( % ) suffix is not valid for line numbers). 


User Action. Specify only integer line numbers in the range 1 to 
32767, inclusive. 


LINNUMINC, line number may not appear in INCLUDE directive file 


Explanation. ERROR - The file specified in a %INCLUDE 
compiler directive contains a line number. 


User Action. Remove the line number from the file. 


LINNUMUND, line number <n> _ undefined due to conditional 
compilation 


Explanation. ERROR - The program references a line number 
that does not appear in the object code as a result of the branch 
taken in a %IF-%THEN-%ELSE-%END-%IF directive. 


User Action. Change the %IF-%THEN-%ELSE-%END-%IF 
directive or remove the line number reference. 


LINREQTWO, LINES output requires at least 2 X,Y points 


Explanation. ERROR - A LINE graphic output statement speci- 
fies less than 2 points. 


User Action. Specify a minimum of 2 points in the LINE graphic 
output statement. 


LNPNOTBP2, programs without line numbers are not allowed in BASIC- 
PLUS-2 


Explanation. INFORMATIONAL - BASIC-PLUS-2 does not 
support programs without line numbers. 


User Action. Add a line number to the first line of the program. 


LOGOPENON, logical operation on non-integer quantity 


Explanation. ERROR - The program contains a logical operation 
performed on strings or real numbers. 


User Action. Change the logical operands to integers. 
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LOOINDMUS, loop control variable must be a numeric variable 


Explanation. ERROR - A FOR statement specifies a string 
variable as the loop control variable. 


User Action. Specify a numeric variable. You can use only 
numeric variables as loop control variables. 


LOOINIMUS, loop initial value must be a numeric expression 


Explanation. ERROR - A FOR statement attempts to assign a 
string expression as the loop control variable’s initial value. 


User Action. Remove the string expression. You can assign only 
numeric values as the loop’s initial value. 


LOOLIMMUS, loop limit must be numeric 


Explanation. ERROR - A FOR statement attempts to assign a 
string expression as the loop control variable’s limiting value. 


User Action. Remove the string expression. You can assign only 
numeric values as the loop control variable’s limiting value. 


LOOWILNEYV, loop will never execute 


Explanation. WARNING - The program contains a FOR/NEXT 
loop that is not executable; for example, FOR 1% = 1% TO 0%. 
Compilation continues, but the loop is ignored. 


User Action. Change the loop parameters or insert an appropri- 
ate STEP clause. 


LOWLSSUP, lower bound must be less than upper bound 


Explanation. ERROR - The lower bound specified in the array is 
greater than the upper bound. 


User Action. Correct the bounds. 


LOWNOTVIR, lower bound not permitted with virtual arrays 


Explanation. ERROR - Lower bounds of virtual arrays must be 
zero. 


User Action. Correct the lower bounds to be zero. 
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LOWNOTZERO, lower bound must be zero 


Explanation. ERROR - The lower bound of the array must be 
zero. 


User Action. Correct the lower bound to be zero. 


LOWRANVAL, range lower value must be less than upper value 


Explanation. ERROR - In the RANGE clause, the first value is 
greater than the second value. 


User Action. Change the range clause so that the first value is 
less than the second value. 


LRSETNOT, <keyword> is not allowed with MID 


Explanation. ERROR - The LSET and RSET keywords are not 
allowed with MID. 


User Action. Change the LSET or RSET keyword to LET. 


MAPDYNNOT, MAP DYNAMIC <map-name> may not be larger than 
32767 bytes 


Explanation. ERROR - A MAP DYNAMIC statement references 
a map that is greater than 32767 bytes in size. 


User Action. Reduce the size of the map, as defined in the MAP 
statement(s), to 32767 bytes or less. 


MAPDYNREQ, MAP DYNAMIC <name> requires corresponding static 
MAP 


Explanation. ERROR - The program contains a MAP DYNAMIC 
statement whose MAP name does not appear in a MAP state- 
ment. 


User Action. Provide a MAP with the same name as the MAP 
DYNAMIC name. 


MAPNOTDEF, MAP <name> used in OPEN not defined 


Explanation. ERROR - An OPEN statement’s MAP clause 
references a nonexistent MAP. 


User Action. Define the MAP referenced by the MAP clause, or 
remove the MAP clause. 
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MAPTOOLAR, MAP too large in OPEN 


Explanation. FATAL - The size of the MAP referenced in an 
OPEN statement is greater than 32767 bytes. 


User Action. Reduce the size of the MAP. 
MAPVARALLT, variable <name> not aligned in multiple references in 
MAP <name> 


Explanation. ERROR - More than one overlaid MAP contains 
the same variable, but the variable’s position differs in the MAPs. 


User Action. The same variable can appear in multiple overlaid 
MAPs, but the variable must occupy the same position in the 
PSECT; make sure that the variable appears in the same position 
in the MAPs. 


MAPVARREF, MAP variable <name> referenced before declaration 


Explanation. INFORMATION - A reference to a MAP variable 
occurs before the MAP statement. 


User Action. Make sure that the MAP statement precedes any 
references to variables in the MAP. 

MATDIMERR, matrix dimension error 
Explanation. ERROR - The program either: 


e Contains a MAT IDN, MAT TRN, or MAT INV performed on 
a one-dimensional array 


e Performs a matrix operation that requires identical sub- 
scripts in the operand arrays and those arrays have different 
subscripts 


User Action. Dimension the arrays to the proper number of 
subscripts. 


MATLOWBOU, matrix must have lower bound 0 and upper bound 4 


Explanation. ERROR - The specified transformation matrix 
either has a lower bound other than 0 or an upper bound other 
than 4. 


User Action. Declare the matrix such that both dimensions have 
a lower bound of 0 and an upper bound of 4. 
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MATMUL20OP, MAT multiply of 2 4X4 matrices required 


Explanation. ERROR - You specified the wrong dimensions in a 
matrix in the MAT multiply statement or a WITH clause on the 

DRAW statement. A 2-dimensional matrix with lower bounds 0 
and upper bounds 4 in both dimensions is required. 


User Action. Declare the matrix to be a 2-dimensional matrix 
with lower bounds 0 and upper bounds 4 in both dimensions. 


MATONEOR2, MAT statements require one or two dimensions 


Explanation. ERROR - A MAT statement references an array of 
more than two dimensions. 


User Action. Remove the array reference. MAT statements are 
valid only on arrays of one or two dimensions. 


MAXCONCOM, maximum conditional compilation depth exceeded 


Explanation. FATAL - Too many nested %IF-%THEN-%ELSE- 
%END-%IF directives are contained in the program. 


User Action. Reduce the number of nested %IF-%THEN- 
%ELSE-%END-%IF directives. You can nest up to eight such 
constructs. 


MAXDIMEXC, maximum number of dimensions exceeded. Maximum 
is 32 


Explanation. ERROR - An array declaration specifies more than 
the allowed number of dimensions. 


User Action. Reduce the number of dimensions to 32 or less. 


MAXKEYSEG, maximum of 8 key segments exceeded 


Explanation. ERROR - An OPEN statement specifies a seg- 
mented key with more than eight segments. 


User Action. Reduce the number of segments in the key clause 
to eight or less. 
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MAXPAREXC, maximum parameters exceeded for <name> . Maximum 
is <number> 


Explanation. ERROR - The program attempts to declare a DEF 
with more than eight parameters or a subprogram with more 
than 255 

parameters. 


User Action. Reduce the number of parameters; DEFs allow up 
to eight parameters and subprograms allow up to 255 
parameters. 


MAXPAREXP, no more than <number> parameter(s) expected for 
<sub-func-name> 


Explanation. ERROR - An external SUB or FUNCTION 
was called with more parameters than were specified in the 
EXTERNAL statement, including both OPTIONAL and non- 
OPTIONAL parameters. 


User Action. Reduce the number of parameters in the call. 


MERGE, merged <item> and <item> 


Explanation. ERROR - The program contains a syntax error. 
VAX BASIC assumes that there is an incorrect space, for example, 
PR INT. Compilation continues so that other errors may be 
detected. The actual program line remains unchanged and no 
object file is produced. 


User Action. Examine the line carefully to discover the error. 
Change the program line to correct the syntax error. 


MINPAREXP, at least <number> parameter(s) expected for 
<sub-func-name> 


Explanation. ERROR - An external SUB or FUNCTION was 
called with fewer parameters than were specified as non- 
OPTIONAL parameters in the EXTERNAL statement. 


User Action. Increase the number of parameters in the call so 
that the number of parameters is equal to or greater than the 
number of non-OPTIONAL parameters. 
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MISENDIF, missing END IF directive before end of program unit 


Explanation. ERROR - A %IF directive crosses a program 
module boundary. 


User Action. Terminate the %IF with a %END %IF before 
beginning a new source module. 


MISENDFOR, missing END <block> for <block> at line <n> 
statement <m> 


Explanation. ERROR - The program contains a SELECT, IF, or 
DEF without a matching END statement. 


User Action. Supply a matching END statement. 


MISMATEND, mismatched END, expected <block> 


Explanation. ERROR - The program contains an incorrect END 
statement, for example, an END RECORD statement instead of 
an END GROUP statement. 


User Action. Supply the correct type of END statement. 


MISMATFOR, missing NEXT for <item> at line <n> _ statement 
<m> 


Explanation. ERROR - The program contains a FOR, WHILE, or 
UNTIL without a matching NEXT. 


User Action. Supply the matching NEXT statement. 


MODNOTEND, module <mod-name> not found in text library 
<text-lib-name> 


Explanation. ERROR - The module name you specified in an 
%INCLUDE directive was not found in the text library you 
specified. 


User Action. Place the module name in the specified text library. 


MULCHRARR, multiple character array name not ANSI 


Explanation. INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains an array whose name 
contains more than one character. 


User Action. Reduce the length of the name to a single 
character. 
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MULCHRDEF, multiple character DEF name not ANSI 


Explanation. INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains a DEF whose name 
contains more than one character. 


User Action. Reduce the length of the name to a single 
character. 


MULDEFLEX, multiple definition of lexical identifier is illegal 


Explanation. ERROR - A lexical constant is named in more than 
one %LET directive. 


User Action. Declare the lexical constant only once with %LET. 


MULHANSPE, multiple handlers specified for WHEN block 


Explanation. ERROR - A WHEN block specifies both an at- 
tached and detached error handler. 


User Action. Change the WHEN block to specify either an 
attached or detached error handler. 


MULNOTBP2, multiple program units per module not BASIC-PLUS-2 
compatible 


Explanation. INFORMATION - A program compiled with the 
/FLAG:BP2COMPATIBILITY qualifier contains more than one 
program unit. BASIC-PLUS-2 does not allow more than one 
program unit in a single file. 


User Action. Separate the program into individual program 
units and compile the units separately. 


MULOPTBAS, multiple OPTION BASE statements not ANSI 


Explanation. ERROR - A program compiled with the /ANSI_ 
STANDARD qualifier contains more than one OPTION BASE 
statement. 


User Action. Specify the OPTION BASE statement only once 
per program. 
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MULPRONOT, multiple program units per module not ANSI 


Explanation. INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains more than one program 
unit. 


User Action. Rewrite the program converting the subprograms 
to subroutines. 


MULSTAPER, multiple statements per line not ANSI 


Explanation. INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains more than one statement 
on a line. 


User Action. Change the program so that each statement has its 
own line number. 


MULTDEF, multiple definition of <name> 


Explanation. WARNING - A variable is declared in more than 
one declarative statement. 


User Action. Make sure that the variable is declared only once. 


NAMNOTREC, name <name> is not of a RECORD component 


Explanation. ERROR - A RECORD component reference uses an 
invalid record name, for example, A::B when A is not a RECORD 
name. 


User Action. Change the erroneous reference. 


NAMTOOLON, name is too long, changed to <name> 


Explanation. WARNING - A variable or array name is longer 
than 31 characters. VAX BASIC truncates the name to 31 char- 
acters and continues compilation so that other errors may be 
detected. The actual program line remains unchanged and no 
object file is produced. 


User Action. Reduce the length of the variable name to 31 or 
fewer characters. 
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NEGFILSTR, negative FILL or string length 


Explanation. ERROR - The program contains a negative FILL 
specification or string length. 


User Action. Change the FILL specification or string length to a 
positive number. 


NESFORLOO, nested FOR loops with same control variable <name> 


Explanation. ERROR - The program contains nested FOR/NEXT 
loops that use the same index variable. 


User Action. Change the index variable for all but one of the 
loops. 


NOBASFRAM, no BASIC frame on stack 


Explanation. ERROR - VAX BASIC could not find a valid 
stack frame. This could be caused by running a program with 
/CHECK=NOBOUNDS or by a non-BASIC subprogram. 


User Action. Debug the program before running with 
/CHECK=NOBOUNDS or check the logic of the non-BASIC 
subprogram. 


NODESCALL, no descriptor allocated for array <name> 


Explanation. ERROR - An immediate mode statement re- 
quired an array descriptor, but it was not available. VAX BASIC 
allocates array descriptors only if the program code requires it. 


User Action. None. 


NODIAGFILE, unsaved changes, no diagnostics file produced 


Explanation. WARNING - The program in memory contains 
changes that have not been saved. Therefore, no diagnostics file 
will be produced from this compilation. 


User Action. SAVE or REPLACE the file. 


NOEDIT, no change made 


Explanation. WARNING - The search string in an EDIT com- 
mand was not located in the text. 


User Action. Enter valid search string. 
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NOFILEALL, a file specification is not allowed with the REPLACE 
command 


Explanation. ERROR - The REPLACE command does not allow 
the use of a file specification. 


User Action. Use either the SAVE command with a file specifi- 
cation or the REPLACE command without one. 


NOFRAME, compiled procedure is currently not active 


Explanation. WARNING - A STOP statement or CTRL/C was 
encountered, and neither the executing procedure nor any of its 
callers was the source compiled as a result of the RUN command. 


User Action. None; you cannot examine or modify a variable in 
immediate mode unless the currently compiled program unit is 
active. If you run a source file containing more than one program 
unit, the currently compiled program is the last program unit in 
the source file. If you use the OLD command to read a program 
into memory and load one or more object modules, then type 
RUN, the currently compiled procedure is the program you read 
into memory with OLD. 


NOHANSPE, no handler specified for WHEN block 


Explanation. ERROR - A WHEN block has been found that does 
not specify an error handler. 


User Action. Specify an error handler for the WHEN block. 


NOLINENUM, missing line number on first line 


Explanation. WARNING - There is no line number on the first 
line of the program. 


User Action. Add a line number to the first line of the program 
or remove all line numbers from the program. 


NOLNROOM, out of memory for line numbers 


Explanation. ERROR - The program contains more line- 
numbered statements than VAX BASIC allows. 


User Action. Change the program so that it uses multi-statement 
lines instead of having each statement on its own line or split the 
program into one or more program units in separate files. 
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NOMAPNAME, MAP statement requires map name 


Explanation. ERROR - A MAP statement does not specify a map 
name. 


User Action. Specify a name for the MAP. 


NOSRCLINE, unsaved changes, no source line debugging available 


Explanation. WARNING - The program in memory contains 
changes that have not been saved. Therefore, no source line 
debugging will be available from this compilation. 


User Action. SAVE or REPLACE the file. 


NOSUCHMAP, no such MAP area <name> 


Explanation. ERROR - A REMAP statement names a nonexistent 
MAP area. 


User Action. Supply a MAP before executing the REMAP 
statement. 


NOTIMP, not implemented in this version 


Explanation. ERROR - The program attempted to use a feature 
that does not exist in this version of VAX BASIC. 


User Action. Examine your program and remove the non- 
implemented feature. 


NOTPASSBY, <item> may not be passed BY <mechanism> 


Explanation. ERROR - The program specifies an incorrect 
passing mechanism for a parameter’s data type, or an invalid 
parameter. For example, you cannot pass an entire array BY 
VALUE, nor can you pass a label as a parameter. 


User Action. Specify a valid parameter or passing mechanism. 


NOTRANS, no main program 


Explanation. WARNING - When a RUN command was typed, 
only subroutines or functions were available. VAX BASIC 
requires a main program to receive the transfer of control. 


User Action. Supply a main program. 
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NOTRECVBY, <item> may not be received by <mechanism> 


Explanation. ERROR - A subprogram specifies an invalid pa- 
rameter or an incorrect passing mechanism for a parameter’s 
data type. For example, you cannot receive an entire array BY 
VALUE. 


User Action. Specify a valid parameter or passing mechanism. 


NOTXTROOM, out of memory for statement text 


Explanation. ERROR - The program contains more text than 
VAX BASIC allows. 


User Action. Split the program into one or more program units. 


NOVALUE, <text> keyword requires a value 


Explanation. ERROR - A keyword command was typed without 
a value. 


User Action. Supply a valid keyword value. 


NUMARREXP, numeric array expected 


Explanation. ERROR - A CHANGE statement does not specify a 
numeric array. 


User Action. Supply a numeric array in the CHANGE statement. 


NUMCONREQ, numeric constant required 


Explanation. ERROR - The program contains a string in a 
context that requires a numeric constant. For example: 


DECLARE INTEGER CONTANT A = "ABC" 


User Action. Supply a numeric constant. 


NUMIS_NEE, numeric expression is required 


Explanation. ERROR - The program contains a string expression 
in a context that requires a numeric expression, for example, 
WHILE A$. 


User Action. Supply a numeric expression. 
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NUMVARREQ, numeric variable required 


Explanation. ERROR - A nonnumeric variable was found with a 
numeric datatype. 


User Action. Specify a numeric variable. 


OBJFAIL, failure in loading object file 


Explanation. FATAL - Either an attempt was made to load 

a non-BASIC object module, or the compiler could not find 
the object file referenced by a CALL statement or EXTERNAL 
FUNCTION reference. 


User Action. If the object file resides in the VAX Common 
Run-Time Library, you must link the program at DCL level. If 
the object file is in a user-supplied library, use the LIBRARY 
command to install the missing object module. You can load 
only VAX BASIC object modules. 


ONENOTWHE, ON ERROR not allowed in WHEN block or handler 


Explanation. ERROR - An ON ERROR statement has been 
found in a WHEN block or an associated error handler. 


User Action. Remove the ON ERROR statement from the 
WHEN block or associated error handler. 


OPEEXPNOT, operator expected, not found 


Explanation. ERROR - A compiler directive contains an invalid 
lexical expression that has a right parenthesis immediately 
followed by a lexical identifier. 


User Action. Correct the lexical expression. 


OPEMUSFOL, operator must follow right parenthesis 


Explanation. ERROR - The program contains an incorrect lexical 
expression. 


User Action. Correct the lexical expression. 


OPENIN, error opening <file-name> as input 


Explanation. ERROR - An error was detected in attempting to 
open a file for input. 


User Action. Make sure the file specification is correct. 
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OPENOUT, error opening <file-name> as output 


Explanation. ERROR - An error was detected in attempting to 
open a file for output. 


User Action. Supply a valid file specification, or take corrective 
action based on the associated message. 


OPNCLAVAL, OPEN clause <clause> value greater than <number> 


Explanation. ERROR - An OPEN statement contains a 
RECORDSIZE, FILESIZE, EXTENDSIZE, WINDOWSIZE, 
BLOCKSIZE, BUCKETSIZE, or BUFFER clause whose argument 
is too large. 


User Action. Supply a smaller value for the argument. 


OPNDUPCLA, duplicate OPEN clause 


Explanation. WARNING - An OPEN statement contains more 
than one clause of the same type. 


User Action. Remove one of the clauses. 


OPNILLCLA, <clause> is an unsupported OPEN clause 


Explanation. ERROR - An OPEN statement specifies invalid 
attributes for the file, for example, CLUSTERSIZE on VAX/VMS 
systems, or uses the keyword COMMON in an I/O clause. 


User Action. Substitute valid attributes for the file or remove the 
COMMON keyword. 


OPNINCCLA, <keyword> keyword is inconsistent with file 
organization 


Explanation. ERROR - An OPEN statement contains a clause 
that is not appropriate for the specified file organization, for 
example, opening a relative file with the ACCESS APPEND 
clause. 


User Action. Remove the inconsistent clause. 
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OPTBASMUS, OPTION BASE must be before array declarations 


Explanation. ERROR - A program compiled with the /ANSI_ 
STANDARD qualifier contains an OPTION BASE statement that 
lexically follows an array declaration. 


User Action. Move the OPTION BASE statement so that it 
lexically precedes the array declaration. 


OPTCLACON, OPTION clause contradicts prior clause 


Explanation. ERROR - The OPTION statement contains contra- 
dictory clauses, for example, specifying the default integer size as 
both BYTE and LONG. 


User Action. Remove one of the clauses. 


OPTNOTALL, OPTIONAL not allowed on EXTERNAL PICTURE 


Explanation. ERROR - An attempt was made to specify the 
OPTIONAL keyword on an EXTERNAL PICTURE declaration. 
This is not allowed because OPTIONAL parameters should be 
used for calling non-BASIC procedures only. 


User Action. Remove the OPTIONAL keyword from the 
EXTERNAL PICTURE declaration. 


OPTOUTSEQ, OPTION statement out of sequence 


Explanation. ERROR - The OPTION statement is either: 1) not 
the first statement in a main program or 2) not the first statement 
following the SUB or FUNCTION statement. 


User Action. Move the OPTION statement so that it is either 
the first statement in the main program or the first statement 
following the SUB or FUNCTION statement in the subprogram. 


ORGUNDREQ, ORGANIZATION UNDEFINED requires FOR INPUT 
clause 


Explanation. ERROR - The program opens a file with 
ORGANIZATION UNDEFINED, but does not specify FOR 
INPUT. 


User Action. Specify FOR INPUT in the OPEN statement. You 
cannot create a file with an undefined file organization. 
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OVFCHKSUP, OVERFLOW checking supported only for INTEGER and 
DECIMAL 


Explanation. ERROR - Overflow checking was specified for a 
floating-point data type in: 1) a compiler command, 2) a qualifier 
to the DCL BASIC command, or 3) an OPTION statement. 


User Action. Specify overflow checking only for INTEGER 
and/or DECIMAL data types. 


OVRNOLINE, <keyword> overrides NOLINE 


Explanation. WARNING - The program: 1) was compiled 
/NOLINES and 2) uses a keyword that requires line number 
information. For example, ERL and RESUME with line number 
both require that the program be compiled /LINES. 


User Action. None. If you use a keyword that requires line 
number information, VAX BASIC automatically overrides the 
/NOLINE qualifier. 


PAREXPFOR, <n> _ parameters expected for <routine> 


Explanation. ERROR - The CALL or invocation of a routine 
specifies a different number of parameters than the number 
specified when the routine was declared. 


User Action. Change the number of parameters to match the 
number declared. 


PARINCPRE, parameter <name> inconsistent with previous declaration 
or reference 


Explanation. ERROR - An external subprogram or DEF function 
declaration specifies a data type for one of the parameters that 
is different than the data type the SUB, FUNCTION, or DEF 
statement specifies. 


User Action. Change the specified data type in either the 
declaration or the SUB, FUNCTION, or DEF statement so that 
the data types agree. 
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PARMODCHA, mode for parameter <n> of routine <name> changed 
to match declaration 


Explanation. INFORMATION - The data type specified in a 
routine invocation does not match that of the routine declaration. 
VAX BASIC issues this message only if the data type conversion 
results in a parameter that cannot be modified by the routine that 
was invoked. 


User Action. Make the data type specifications in the declaration 
and the invocation match. 


PARMODNOT, mode for parameter <n> of routine <name> not as 
declared 


Explanation. ERROR - The CALL or invocation of a routine 
specifies a string argument for a parameter that was specified as 
a numeric when the routine was declared, or vice versa. 


User Action. Change the string parameter to numeric, or vice 
versa. 


PARNOTENT, parenthesis illegal, entire array required context 


Explanation. ERROR - Parenthesis are used to specify an entire 
array in a context where an entire array is always required. 


User Action. Remove the empty parenthesis from the entire 
array reference. 


PARSTRNOT, parameter <n> of <type> structure not as declared 


Explanation. ERROR - The actual parameter list in subprogram 
CALL or an invocation specifies an entire array where the 
subprogram declaration specified a simple variable or vice versa. 


User Action. Change the actual parameter list to match the 
declared parameter list or vice versa. 


PARTYPREQ, parameter type specification required with /EXPLICIT 


Explanation. ERROR - In a program compiled with 
/TYPE=EXPLICIT, no data type keyword is specified for a 
parameter. 


User Action. Supply a data type keyword for the parameter. 
There are no default data types when you compile a program 
with /TYPE=EXPLICIT. 
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PASMECDEF, passing mechanism not allowed for DEF 


Explanation. ERROR - A DEF function declaration specifies a 
passing mechanism for a parameter. 


User Action. Remove the passing mechanism clause. 


PASMECDIS, passing mechanism disagrees with declaration 


Explanation. ERROR - The CALL or invocation of a routine 
specifies a different passing mechanism for a parameter than that 
specified when the routine was declared. 


User Action. Remove the BY clause specified in the CALL or 
invocation; VAX BASIC automatically passes parameters with the 
passing mechanism specified when the routine was declared. 


PASMECNOT, passing mechanism not allowed for <item> 


Explanation. ERROR - A program specifies a passing mechanism 
in a context other than the invocation or declaration of an 
external subprogram. 


User Action. Remove the passing mechanism clause. 


PASWITNO, <name> has a passing mechanism specified with no 
parameter list 


Explanation. WARNING - A CALL statement, external function 
reference, or EXTERNAL statement specifies a BY clause but does 
not specify a formal parameter list. 


User Action. Remove the BY clause or supply a parameter list. 


PATNOTREC, path name does not specify a CDD record 


Explanation. ERROR - The %INCLUDE directive contains an 
invalid path name for a record definition. 


User Action. Supply a valid path name for a record definition. 


PICWHINOT, exit from PICTURE while not in PICTURE 


Explanation. ERROR - An EXIT PICTURE statement was found 
in a module that is not a PICTURE subprogram. 


User Action. Remove the EXIT PICTURE statement. 
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POIREQONE, POINTS output requires at least 1 X,Y point 


Explanation. ERROR - You do not specify a point in the POINT 
graphic output statement. 


User Action. Specify a minimum of 1 point in the POINT 
graphic output statement. 


POSGTRTAR, starting position greater than target length 


Explanation. ERROR - The starting value in the MID statement 
is greater than the length of the string. 


User Action. Correct the value to be less than or equal to the 
length of the string. 


PRELOGNAM, previous logical name assignment replaced 


Explanation. INFORMATION - The specified logical name 
already existed. The new equivalence name replaces the old one. 


User Action. None. 


PRICDDERR, prior severe CDD error 


Explanation. ERROR - There have been one or more severe 
CDD errors, and this may be the reason for the following errors. 


User Action. Recompile the program after correcting the first 
CDD-related errors. 


PRIUSICLA, PRINT USING clause must be a string expression 


Explanation. ERROR - A PRINT USING statement specifies a 
numeric format string. 


User Action. Supply a valid format string. 


PRIUSICON, PRINT USING conflicts with RECORD clause 


Explanation. ERROR - A PRINT USING statement contains a 
RECORD clause. 


User Action. Remove the RECORD clause or use the PRINT 
statement instead of PRINT USING. 
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PROSTRNES, program structures nested too deeply 


Explanation. FATAL - The program contains too many nested 
block constructs, for example, DEF function definitions. 


User Action. Reduce the number of nested block constructs. 


PROTOOBIG, program too big to compile 
Explanation. FATAL - The program is too big. 


User Action. Recode the program as two or more modules. 


PROWHINOT, exit from PROGRAM while not in a main program 


Explanation. ERROR - An EXIT PROGRAM statement was 
found in a program unit that is not a main program. 


User Action. Use the type of EXIT appropriate to the program 
unit. 


QUALERR, unknown qualifier <name> 


Explanation. ERROR - An attempt was made to enter an invalid 
qualifier to a SET, LOCK, or COMPILE command. 


User Action. Enter the SET, LOCK, or COMPILE command with 
the correct qualifier. 
RADNOTSUP, radix not supported 


Explanation. ERROR - A literal constant specifies a radix. For 
example, in the following DECLARE statement, H is an invalid 
radix specifier: 


10 DECLARE LONG CONSTANT A = H"111" 


User Action. Specify a valid radix. See the VAX BASIC Reference 
Manual for a list of the radices VAX BASIC allows. 
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REAACCINC, READ access inconsistent with FOR OUTPUT 


Explanation. ERROR - An OPEN statement specifies FOR 
OUTPUT and ACCESS READ. 


User Action. FOR OUTPUT specifies that a new file is created; 
ACCESS READ specifies that the program can only read the 
file. If you want to create a new file, remove the ACCESS 
READ clause; if you want read-only access to a file, specify FOR 
INPUT. 


READERR, error reading <file-name> 


Explanation. ERROR - An error was detected in attempting to 
read a file. 


User Action. Supply a valid file specification or take corrective 
action based on the associated message. 


REAWITDAT, READ without DATA statement 


Explanation. ERROR - The program contains a READ statement 
and there are no DATA statements. 


User Action. Supply a DATA statement or remove the READ 
statement. 


RECENTARR, RECORD entire array must not have subfields specified 


Explanation. ERROR - A RECORD component reference speci- 
fies an array before the end of the component path, for example, 
A::B(,)::C. 


User Action. Remove the erroneous reference. 


RECFILTOO, <field-name> from CDD has FILL too large 


Explanation. ERROR - The total size of a CDD record is greater 
than 65535 bytes. 


User Action. Reduce the size of the record. 
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RECKEYQAD, entire RECORD or GROUP must be 8 bytes in length 


Explanation. ERROR - The user attempts to specify an entire 
RECORD or GROUP name in a key value field on a GET or 
FIND statement and the size of the structure does not match the 
size of the QUADWORD. 


User Action. When specifying a quadword key, use an 8 byte 
RECORD or GROUP. Otherwise, specify the name of an elemen- 
tary item in the RECORD or GROUP. 


RECNOTBY, record may not be passed BY <mechanism> 


Explanation. ERROR - The program attempts to pass a record 
to a subprogram using either the BY VALUE or BY DESC 
parameter-passing mechanism. 


User Action. Remove the passing mechanism, or specify BY 
REF. VAX BASIC programs can pass records only by reference. 


RECNOTDEF, record type <name> not defined 


Explanation. ERROR - The program declares an instance of a 
user data type, but this type was not defined in the program 
module. 


User Action. Define the data type with a RECORD statement. 


RECOVEMAP, RECORDSIZE overflows MAP 


Explanation. ERROR - An OPEN statement contains both a 
RECORDSIZE clause and a MAP clause, and the RECORDSIZE 
clause is larger than the MAP. 


User Action. Make the RECORDSIZE the same as the MAP size. 


RECRECDEF, recursive RECORD definition of type <name> 


Explanation. ERROR - The program contains two or more 
RECORD statements that reference each other. 


User Action. Change the program so that the RECORD state- 
ments do not point at each other. 
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RECTOBIGL, record too big from module <mod-name~> in text library 
<text-lib-name> 


Explanation. ERROR - the text library module specified in an 
%INCLUDE directive contains a record longer than 255 bytes. 


User Action. Extract the module from the text library, edit it 
to remove any records longer than 255 bytes, and replace the 
module in the text library. 


RECTOOBIG, record too big from INCLUDE directive file 


Explanation. ERROR - The file specified in an %INCLUDE 
directive contains a record longer than 255 bytes. 


User Action. Edit the file to remove any records longer than 255 
bytes. 


RECTOOLAR, RECORD <name> too large. Limit is 65535 bytes. 


Explanation. ERROR - The components of a RECORD definition 
add up to more than 65535 bytes. 


User Action. Reduce the size of the RECORD. 


REMARRREF, entire REMAPPED array <name> cannot be passed BY 
REF 


Explanation. ERROR - The program attempts to pass an ar- 
ray declared in a MAP DYNAMIC statement to an external 
subprogram by reference. 


User Action. Entire remapped arrays must be passed by de- 
scriptor. Specify the BY DESC passing mechanism either in the 
EXTERNAL declaration or the subprogram invocation. 


REMNOTALL, REM statement not allowed in programs without line 
numbers 


Explanation. ERROR - A REM statement has been found in a 
program without line numbers. 


User Action. Remove the REM statement. 
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REPLACE, assuming <operator(s)> replaced by <operator> 


Explanation. ERROR - The program contains a syntax error. 
VAX BASIC found incorrect or multiple operators where another 
single operator makes more sense, for example, 10 A == 
Compilation continues so that other errors may be detected. 
The actual program line remains unchanged and no object file is 
produced. 


User Action. Examine the line carefully to discover the error. 
Change the program line to correct the syntax error. 


REQNUMEXP, <item> requires a numeric expression 


Explanation. ERROR - The program contains a string expression 
in a context requiring a numeric expression. 


User Action. Supply a numeric expression. 


REQSTREXP, <item> requires string expression 


Explanation. ERROR - The program contains a numeric ex- 
pression in a context requiring a string expression, for example, 
the file specification in an OPEN statement or the default file 
specification in a DEFAULTNAME clause. 


User Action. Supply a string expression. 


RESABOCON, RESEQUENCE aborted due to conditional compilation 


Explanation. ERROR - A resequenced program contains a 
%IF-%THEN-%ELSE-%END-%IF directive. 


User Action. Remove the %IF-%THEN-%ELSE-%END-%IF 
directive. 


RESABOSYN, RESEQUENCE aborted due to syntax error 


Explanation. ERROR - A RESEQUENCE operation was termi- 
nated because the program was not syntactically correct. 


User Action. Correct the syntax error and retry the 
RESEQUENCE operation. 
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RESATTINC, result attributes inconsistent with prior declaration 


Explanation. ERROR - An external or DEF function declaration 
specifies a data type for the function’s result, which is different 
than the data type the DEF or FUNCTION statement specifies. 


User Action. Change the specified data type in either the 
declaration or the DEF or FUNCTION statement so that the data 
types agree. 


RESINCLIN, RESEQUENCE cannot be used if INCLUDE files reference 
line numbers 


Explanation. ERROR - The current program references an 
include file that contains line number references, for example, 
GOTO. 


User Action. Remove the %INCLUDE directive. VAX BASIC 
cannot resequence lines in an INCLUDE file. 


RESLINGTR, RESEQUENCE cannot generate line numbers greater than 
32767 


Explanation. ERROR - The RESEQUENCE command specified 
an interval or starting point that would have created a line 
number greater than 32767. 


User Action. Reduce the interval or the starting point. 


RESNOTWHE, RESUME not allowed in WHEN block or handler 


Explanation. ERROR - A RESUME statement has been found in 
a WHEN block or an associated error handler. 


User Action. Remove the RESUME statement from the WHEN 
block or associated error handler. 


RESORDLIN, RESEQUENCE cannot change the order of or delete lines 


Explanation. ERROR - The RESEQUENCE command specifies 
invalid source program changes. 


User Action. Supply a valid RESEQUENCE command. 
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RETCONMUS, RETRY and CONTINUE must appear in error handlers 


Explanation. ERROR - A RETRY or CONTINUE statement is 
not in an error handler associated with a WHEN block protected 
region. 


User Action. Remove the RETRY or CONTINUE statement. 


RFAEXPREQ, RFA expression required 


Explanation. ERROR - A GET BY RFA statement contains an 
expression that is not of the RFA data type. 


User Action. Supply a valid RFA expression. 


RFANOTALL, RFA not allowed in this context 


Explanation. ERROR - The program attempts to use an RFA 
expression in an arithmetic expression or other invalid context. 


User Action. Remove the RFA expression. You can use the RFA 
data type only in file 1/O, in an assignment statement, or in a 
comparison. 


ROUSUPDEC, ROUNDing supported only for DECIMAL 


Explanation. ERROR - Rounding was specified for a non- 
DECIMAL data type in: 1) a compiler command, 2) a qualifier to 
the BASIC DCL command, or 3) an OPTION statement. 


User Action. Specify rounding only for the DECIMAL data type. 


RPTCOUMUS, repeat count must be positive numeric 


Explanation. ERROR - A FILL item specifies a nonnumeric or 
negative repeat count, for example, FILL(A$) or FILL(-3). 


User Action. Supply a valid repeat count. 


SCAFACINH, SCALE factor inhibits optimization 


Explanation. INFORMATION - This error is reported only 
when the /SETUP qualifier is in effect. Specifying a scale factor 
prevents optimization of the compiler-generated code. 


User Action. Compile the program without specifying a scale 
factor. 
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SCALEO, scale factor used is 0 for single precision 


Explanation. WARNING - An attempt was made to set the 
SCALE factor while in single precision. 


User Action. Set the precision to /DOUBLE. You cannot use 
scaling when in single precision. 


SCAOUTRAN, SCALE is out of range. Valid is 0 to 6. 


Explanation. ERROR - The OPTION statement specifies a scale 
factor that is not between zero and six, inclusive. 


User Action. Supply a valid scale factor. 


SEQERR, attempt to sequence over existing statement 


Explanation. ERROR - A SEQUENCE command specifies a 
starting line number that already exists in the VAX BASIC source 
program in memory. 


User Action. Specify a starting line number higher than any 
existing line or delete the old statement before using the 
SEQUENCE command. 


SEVINTERR, severe internal error has been detected. Submit an SPR. 


Explanation. FATAL - An error has been detected in the VAX 
BASIC compiler. 


User Action. Please submit an SPR with the source code of a 
small program that produces this error. 


SPANOSPA, SPAN is inconsistent with NOSPAN 


Explanation. WARNING - An OPEN statement specifies both 
SPAN and NOSPAN. 


User Action. Remove one of the clauses. 
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SEVERRSCA, please submit an SPR—internal error in SCA support 


Explanation: FATAL - A severe error has been detected in the 
SCA support in the VAX BASIC compiler. If you recompile your 
program without the /ANALYSIS_DATA qualifier, this error 
should no longer occur. 


User Action: Please submit an SPR with the source code of a 
small program that produces the error. 


SEVINTERR, severe internal error has been detected. Submit an SPR. 


Explanation: FATAL - An error has been detected in the 
VAX BASIC compiler. 


User Action: Please submit an SPR with the source code of a 
small program that produces this error. 


SHRNOTAVL, Unable to access the shareable image <name> 


Explanation: ERROR - The shareable image is not available on 
your system. 


User Action: Install the correct version of the required shareable 
image. 


SPANOSPA, SPAN is inconsistent with NOSPAN 


Explanation: WARNING - An OPEN statement specifies both 
SPAN and NOSPAN. 


User Action: Remove one of the clauses. 
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SPELL, assuming <item> intended to be the keyword: <keyword> 


Explanation. ERROR - The program contains a syntax error. 
VAX BASIC assumes that a keyword has been misspelled, and 
compilation continues so that other errors may be detected. The 
actual program line remains unchanged and no object file is 
produced. 


User Action. Examine the line carefully to discover the error. 
Change the program line to correct the syntax error. 


SPENUMEXC, specified numeric exceeds valid character code 


Explanation. ERROR - A quoted literal of type character (C) 
contains a value outside the valid range, for example, '300'C. 


User Action. Use a valid ASCII value. 


STACKOVF, stack frame overflow for variables 


Explanation. ERROR - The program requires too much space for 
dynamic variables. 


User Action. Reduce the number of dynamic variables or place 
some of the variables in a MAP or COMMON. 


STANOTALL, statement not allowed within a PICTURE definition 


Explanation. ERROR - The statement you specified is not 
allowed in a PICTURE definition. 


User Action. Remove the statement from the PICTURE 
definition. 
STARISNEE, star (*) is needed in DEF, not “/” 


Explanation. ERROR - The program contains a statement that 
starts with DEF /. 


User Action. Change the DEF/ to DEF*. 


STRARRNOT, string array not ANSI 


Explanation. INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains a string array. 


User Action. Remove the string array. 
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STRCONEXP, string constant expression is too long 


Explanation. ERROR - The program contains a DECLARE 
STRING CONSTANT statement where the value assigned to the 
constant exceeds the maximum number of characters allowed 
for string constant expressions. The maximum length of a string 
constant expression at compile-time is 498 characters. 


User Action. Change the string constant to a string variable and 
assign the string expression to the variable at run-time. 


STRCONREQ, string constant required 


Explanation. ERROR - The program contains a numeric expres- 
sion in a context that requires a string expression, for example: 


DECLARE STRING CONSTANT ABC = 123 


User Action. Supply a string literal or a named string constant. 


STRDEFNOT, string DEF not ANSI 


Explanation. INFORMATION - A program compiled with the 
/ANSI_STANDARD qualifier contains a string DEF. 


User Action. Remove the string DEF. 


STRLENANY, string length not allowed on ANY 


Explanation. ERROR - An ANY parameter specifies a string 
length in an EXTERNAL statement. This is not allowed because 
ANY implies that you can use any data type, not specifically a 
string data type. 


User Action. Remove the string length specification from the 
ANY clause. 


STRIS_NEE, string expression is required 


Explanation. ERROR - The program contains a numeric expres- 
sion where a string expression is needed, for example, NAME 
1% AS “ABC.DAT’. 


User Action. Supply a string expression. 
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STRLENDYN, string length not allowed on MAP DYNAMIC variable 


Explanation. ERROR - A string variable in a MAP DYNAMIC 
statement specifies a string length. 


User Action. Remove the string length. All string variables 
named in a MAP DYNAMIC statement have a length of zero 
until a REMAP statement executes. 


STRLENINC, virtual array string <name> length increased from <n> 
to <m> 


Explanation. WARNING - In a string virtual array DIM state- 
ment, the specified string length is not a power of two. 


User Action. None. VAX BASIC increases the string length to 
the next higher power of two. 


STRLENMUS, string length specification for <name> must be numeric 


Explanation. ERROR - The length specification for a fixed-length 
string is nonnumeric, for example, COMMON A$ = “ABC”. 


User Action. Supply a numeric length specification. 


STRLENNOT, string length not allowed on numeric variable <name> 


Explanation. ERROR - The declaration for a numeric variable 
contains a string length specification. 


User Action. Remove the string length specification. 


STRLENTRU, virtual array string <name> length truncated from <n> 
to <m> 


Explanation. WARNING - A string virtual array specifies a 
string length greater than 512. VAX BASIC truncates the length 
specification to 512. 


User Action. None. The maximum string length for virtual 
arrays is 512. 


STRLITREQ, string literal required for compiler directive 


Explanation. ERROR - A quoted string is missing in a compiler 
directive that requires one, for example, %IDENT. 


User Action. Supply a string literal for the compiler directive. 
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STROUTRAN, string is too large 


Explanation. ERROR - A string exceeds the maximum allowable 
length. The maximum length is 65535 characters. 


User Action. Reduce the length of the string. 


STRRECFIE, string record element may not be FIELDed 


Explanation. ERROR - A FIELD statement contains a string 
record element as the fielded variable. 


User Action. Replace the string record element with a dynamic 
string. Fielded variables must be dynamic. 


STRRECFOR, stream format must have sequential organization 


Explanation. ERROR - A file was opened using STREAM 
as a record format, but the specified organization was not 
SEQUENTIAL. 


User Action. Change the OPEN statement so that it specifies 
ORGANIZATION SEQUENTIAL. 


STRVAREXP, string variable expected 


Explanation. ERROR - A CHANGE statement specifies a nu- 
meric variable. 


User Action. Supply a string variable; the CHANGE statement 
changes a string variable to a numeric array and vice versa. 


STRVARREQ, string variable required 


Explanation. ERROR - A statement references a numeric vari- 
able instead of a string variable, for example, LINPUT A%. 


User Action. Supply a string variable instead of a numeric 
variable. 


SUBMAYNOT, subscript may not be specified for entire array 


Explanation. ERROR - A CALL statement or external function 
reference passes an entire array as a parameter and contains a 
subscript expression, for example, A(,,3). 


User Action. Remove the subscript expression. You cannot spec- 
ify any subscripts when passing an entire array as a parameter. 
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SUBOUTRAN, subscript out of range for <array-name> 


Explanation. ERROR - The program references an array element 
with constant subscript(s) outside the bounds of the array. 


User Action. Check program logic to make sure all subscripts 
are within the bounds of the array. 


SUBRECCOM, subscripting error in RECORD component 


Explanation. ERROR - The program contains a RECORD 
component reference with invalid subscripts, for example, 
A::B(1,2)::C where B has only one subscript, or A::B where A 
requires a subscript. 


User Action. Change the erroneous reference. You must specify 
as many subscripts as were defined in the RECORD. 


SUBWHINOT, exit from SUB seen while not in SUB 


Explanation. ERROR - A program contains an EXIT SUB or 
SUBEXIT statement with no preceding SUB statement. 


User Action. If the program is a subprogram, supply a SUB 
statement; otherwise, remove the EXIT SUB or SUBEXIT 
statement. 


SUFFILNOT, suffix not allowed on FILL after datatype keyword 


Explanation. ERROR - A FILL item defined with an explicit data 
type ends in a percent or dollar sign. 


User Action. Remove the FILL item’s percent or dollar sign. 


SUFINTONLY, % only allowed with BYTE, WORD, LONG, or INTEGER 
keywords 


Explanation. ERROR - The % suffix is only allowed on integer 
data types. 


User Action. Remove the % suffix from the variable name or 
change the data type keyword. 
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SUFNOTALL, suffix not allowed on variable <name> 


Explanation. ERROR - A name, which cannot end in a percent 
sign or dollar sign, such as a label name, ends with either a 
percent sign or dollar sign. 


User Action. Remove the variable’s percent or dollar sign. 


SUFNOTHAN, suffix not allowed on HANDLER <name> 


Explanation. ERROR - A HANDLER name ends in a percent or 
dollar sign. 


User Action. Remove the percent or dollar sign from the 
HANDLER name. 


SUFNOTREC, suffix not allowed for record type 


Explanation. ERROR - A record definition specifies a user- 
defined record type that ends in a percent or dollar sign. 


User Action. Remove the record type’s percent or dollar sign. 


SUFSTRONLY, $ is only allowed with STRING keyword 


Explanation. ERROR - The $ suffix is only allowed on string 
data types. 


User Action. Remove the $ suffix from the variable name or 
change the data type keyword. 


SYNNOTANS, syntax check mode not allowed when ANSI 


Explanation. ERROR - A SET /SYNTAX_CHECK command 
was entered when the /ANSI_STANDARD qualifier was in 
effect. 


User Action. None; syntax checking is not supported in ANSI 
mode. 


SYSERROR, system service error 


Explanation. ERROR - An error was detected while executing a 
system service. 


User Action. Take corrective action based on the associated 
message. 
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TEXFOLEND, text following end of program unit must be on new 
<type of line> line 


Explanation: ERROR - The compiler detected text following an 
END, END SUB, or END FUNCTION statement. 


User Action: Remove the text. In a multi-module source file 
with line numbers, any text following an END, END SUB, or 
END FUNCTION statement must begin on a numbered line. 
In a multi-module source file without line numbers, any text 
following an END, END SUB, or END FUNCTION statement 
must begin on a new physical line. 


TEXLINMSG, text line exceeded 255 characters 


Explanation: INFORMATION - An input line contains more 
than 255 characters. VAX BASIC saves the first 255 input 
characters into the line buffer and ignores the rest of the input. 


User Action: Supply no more than 255 characters per input line 
to avoid truncation of input. 


TEXPATMUS, text path must be “RIGHT”, “LEFT”, “UP” or “DOWN” 


Explanation: ERROR - You specified an invalid value for the 
path specification of the SET TEXT PATH statement. 


User Action: Specify one of the values listed in the message. 


TEXPREMUS, text precision must be “STROKE”,“CHAR’ or “STRING” 


Explanation: ERROR - You specified an invalid value for the 
text precision of the SET TEXT FONT statement. 


User Action: Specify one of the values listed in the message. 


THEMUSFOL, THEN directive must follow a lexical expression 


Explanation: ERROR - A %IF directive contains a lexical expres- 
sion that is not immediately followed by a % THEN. 


User Action: Supply a %THEN clause. %THEN, %ELSE, and 
%END %IF are required in a %IF directive. 
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TOMCHINFO, extra information on command line has been ignored 


Explanation: INFORMATION - You supplied an argument to a 
CONTINUE, EXIT, IDENTIFY, or SCRATCH command. These 
commands do not accept arguments. VAX BASIC ignores the 
extra data and executes the command. 


User Action: Remove the argument from the command. 


TOOFEWARG, too few arguments 


Explanation: ERROR - The invocation of a VAX BASIC built-in 
function contains too few arguments. 


User Action: Supply the correct number of arguments to the 
function. 


TOOMANARG, too many arguments 


Explanation: ERROR - The invocation of a VAX BASIC built-in 
function contains too many arguments. 


User Action: Supply the correct number of arguments to the 
function. 


TOOMANIND, too many array indices active 


Explanation: ERROR - A subscript expression contains more 
than 100 array indices between the open parenthesis and the 
close parenthesis. 


User Action: Reduce the number of active array indices. 


TOOMANKEY, too many keys - limit is 255 


Explanation: ERROR - An OPEN statement specifies more than 
255 index keys. 


User Action: Reduce the number of index keys. The maximum 
is 255. 


TOOMANPAR, too many function parameters active 


Explanation: ERROR - An external function invocation contains 
too many expressions in the actual parameter list. 


User Action: Reduce the number of expressions in the actual 
parameter by assigning the expressions to temporary variables. 
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TRAFUNONL, Transformation functions only permitted with multiplication 


Explanation: ERROR - A graphics transformation function is 
used in a MAT statement other than matrix multiplication. 


User Action: Remove the transformation function from the MAT 
statement. 


TRAOUTRAN, transformation number must be in the range 1 - 255 


Explanation: ERROR - You specified a transformation number 
that is less than 1 or greater than 255. 


User Action: Change the transformation number to be within 
the range 1 to 255. 
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TYPDEFSTR, TYPE default of STRING is not allowed. 


Explanation: ERROR - STRING was specified as the default data 
type in: 1) a compiler command, 2) a qualifier to the DCL BASIC 
command, or 3) an OPTION statement. 


User Action: Specify a numeric data type as the default. 


UNDEFINED, unresolved/undefined symbols 


Explanation: ERROR - A program executed in the BASIC 
environment calls or invokes a subprogram or routine that has 
not been loaded. 


User Action: Load the subprogram or routine before running the 
program in the BASIC environment. 


UNDLINNUM, undefined line number 


Explanation: ERROR - A statement tries to transfer control to a 
nonexistent line. Or, in a numberless program, a line number is 
referenced. 


User Action: Replace the nonexistent line number with the 
correct destination line number or label. 


UNELEXDIR, unexpected lexical directive encountered 


Explanation: ERROR - The specified lexical directive is not legal 
in this statement. 


User Action: Use a supported lexical directive. 


UNEXPEOF, unexpected end of file 


Explanation: ERROR - An end-of-file was specified immediately 
after an ampersand continuation character. 


User Action: Remove the ampersand continuation character or 
continue the line. 


UNKCOMINP, unknown command input 


Explanation: ERROR - An attempt was made to enter an invalid 
or unknown command. 


User Action: Enter the VAX BASIC command correctly. 
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UNLINCREA, UNLOCK EXPLICIT clause inconsistent with ACCESS READ 


Explanation: ERROR - An OPEN statement contains both an 
ACCESS READ and an UNLOCK EXPLICIT clause. This is 
inconsistent because ACCESS READ specifies no record locking 
while UNLOCK EXPLICIT specifies that all accessed records 
remain locked until explicitly unlocked. 


User Action: Either remove the UNLOCK EXPLICIT clause or 
change the ACCESS clause. 


UNSCDDLEV, unsupported CDD level <number> . Supported level is 
<number > 


Explanation: ERROR - The current CDD version is incompatible 
with VAX BASIC. 


User Action: Use a supported version of the CDD. 


UNTSTRLIT, unterminated string literal 


Explanation: ERROR - The program contains an improperly 
terminated string literal; for example, “ABC , “ABC’, and ‘ABC’ 
are all improperly terminated. 


User Action: Use the same type of quotation mark (either single 
or double) for both beginning and ending string delimiters. 


USEONLALO, USE only allowed inside WHEN blocks 


Explanation: ERROR - A USE statement is not within a WHEN 
block. 


User Action: Remove the USE statement. 


USERABORT, user ABORT directive <text> 


Explanation: FATAL - The compilation was terminated as the 
result of a % ABORT directive. The compiler prints the text 
following the % ABORT. 


User Action: None. 
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USERPRINT, <text> 


Explanation. SUCCESS - The compilation found a %PRINT 
directive and printed the specified message to the terminal and 
listing file. 


User Action. None. 


USEVARNOT, user variable <name> not allowed in declaration 


Explanation. ERROR - The parameter list in an external subpro- 
gram declaration contains a user variable name. 


User Action. Remove the variable from the parameter list. 
When declaring a routine, the parameter list can contain only 
data type and parameter-passing mechanism specifications. 


VALTOOLAR, value too large for constant 


Explanation. WARNING - The value of an EXTERNAL 
CONSTANT is larger than the specified data type allows. 


User Action. Make sure the data type specified in the 
EXTERNAL CONSTANT statement matches that of the actual 
constant. 


VALUEREQ, PRINT USING requires a value 


Explanation. ERROR - A PRINT USING statement must have at 
least one expression or value. 


User Action. Supply an expression or value at the end of the 
PRINT USING statement. 


VARCONREQ, variable or constant required 


Explanation. ERROR - The program contains an executable DIM 
statement that contains an expression in the bounds list. 


User Action. Remove the expression from the bounds list. 
Executable DIM statements can have only constants or variables 
(simple or subscripted) as bounds. 
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VERJUSMUS, vertical justification must be “TOP”, “CAP’,“HALF”,”“BASE”, 
“BOTTOM” or “NORMAL” 


Explanation. ERROR - You specified an invalid value for the 
vertical component of the SET TEXT JUSTIFY statement. 


User Action. Specify one of the values listed in the message. 


VIRARROVE, virtual array space exceeded at array <name> 


Explanation. ERROR - The storage for virtual arrays on a single 
channel exceeds 2147483647 bytes. 


User Action. If there is only one virtual array on the channel, 
you must reduce the amount of storage used by the array. 
However, if there is more than one virtual array on the channel, 
you can put each array on a separate channel. 


VIRNOTALL, virtual array not allowed in graphics statements 


Explanation. ERROR - You specified an entire virtual array on a 
statement that does not allow them. 


User Action. Specify a non-virtual array in place of the virtual 
array. 


VIRRECTOO, virtual RECORD <name> is too large. Limit is 512 bytes 


Explanation. ERROR - The elements of a virtual array are of 
type <name> and the total storage requirement for each 
element is greater than 512 bytes. 


User Action. Reduce the size of the RECORD. 


WRITEERR, error writing <file-name> 


Explanation. ERROR - An error was detected in attempting to 
write to a file. 


User Action. Supply a valid file specification or take corrective 
action based on the associated message. 


WROTYPLIB, library <lib-name> is not an OBJECT or IMAGE library 


- Explanation. WARNING - The logical BASIC$LIBn translates to 
a library that is not an object library or a shareable image library. 


User Action. Change the logical BASIC$LIBn to translate to an 
object library or a shareable image library. 
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XYPOIREQ, X,Y point required between semicolons 


Explanation. ERROR - In a list of points in a statement such as 
PLOT LINES, you specified two semicolons in a row without an 
X,Y point specification between them. 


User Action. Either supply another point or remove the extra 
semicolon. 
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Appendix B 
Run-Time Error Messages 


VAX BASIC returns run-time error messages if an error occurs while a 
program is executing. The error is diagnosed and for programs without 
line numbers, VAX BASIC indicates the program line that generated the 
error. Warning error messages indicate that an error has occurred, but 
program execution continues. In some cases, VAX BASIC reprompts for 
more information or correct data; in other cases, VAX BASIC performs 
the specified operation, but the results are not as expected. Fatal error 
messages indicate that the program has aborted. You can recover from 
most fatal errors by including error-handling routines in your program 
and by specifying OPTION HANDLE = FATAL. Certain errors, however, 
are not recoverable even when error-handlers are used. In the description 
of these errors they are designated as not trappable. You do not need 
error-handling routines to trap errors that generate warning messages. 


Section B.1 of this appendix lists VAX BASIC run-time errors, alphabetized 
by mnemonic code. Section B.2 is a cross reference numerical listing of 
run-time errors generated by VAX BASIC; Section B.3 lists error messages 
which VAX BASIC does not generate, but which can be displayed with 
the ERT$ function. See the VAX BASIC Reference Manual for information 
about RMSSTATUS and VMSSTATUS. 


B.1 VAX BASIC Run-Time Errors by Mnemonic 


The VAX BASIC error message format is: 


“BAS-<1>-<mnemonic>, <message> 
-BAS-I-FROLINMOD, from Line x in module y 


Run-Time Error Messages B-1 


<I> 
Is a letter indicating the severity of the error. The severity indicator 
can be one of the following: 
e I, indicating information 
e W, indicating a warning 
e _E, indicating an error 
e F, indicating a severe error 


<mnemonic> 
Is a 3- to 9-character string that identifies the error. 


<x> 
Is the line number where the error occurred. 


<y> 
Is the name of the module where the error occurred. 


Warning error messages indicate that an error has occurred, but program 
execution continues. In some cases, VAX BASIC reprompts for more 
information or correct data; in other cases, VAX BASIC performs the spec- 
ified operation, but the results are not as expected. Fatal error messages 
indicate that the program has aborted. 

ARGDONMAT, Arguments don’t match (ERR=88) 


Explanation. The proper array descriptor was not specified for a 
matrix operation. 


User Action. Use VAX BASIC to create the array. 
ARGTOOLAR, Argument too large in EXP (ERR=49) 


Explanation. The program contains: 


e An argument to the EXP function larger than 88 


e An exponentiation operation that results in a number greater 
than 1E38 


User Action. Change the EXP argument to be in the valid range, 
or reduce the size of the exponent. 
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ARRMUSSAM, Arrays must be same dimension (ERR=238) 


Explanation. The program attempts to perform matrix addition 
or subtraction on input arrays with a different dimensions. 


User Action. Use arrays that have identical dimensions. 


ARRMUSSQU, Arrays must be square (ERR=239) 


Explanation. The program attempts matrix inversion (MAT INV) 
on an array that is not inversible. 


User Action. Use only square arrays when performing a matrix 
inversion. 


ARRTOOSMA, Array too small (ERR=197) 


Explanation. The array you referenced with a graphics statement 
is too small. Check the description of the graphics statement to 
get the minimum size requirement for the array. 


User Action. Increase the size of the array. 


BADDIRDEV, Bad directory for device (ERR=1) 


Explanation. The device directory does not exist or is 
unreadable. 


User Action. Supply a valid directory. 


BADRECIDE, Bad record identifier (ERR=143) 


Explanation. The program attempted a record access that 
specified: 


e A zero or negative record number on a RELATIVE file 
e A null key value on an INDEXED file 


User Action. Change the record number or key specification to a 
valid value. 


BADRECVAL, Bad RECORDSIZE value on OPEN (ERR=148) 


Explanation. The value in the RECORDSIZE clause in the 
OPEN statement either (1) is zero or greater than 65535 or (2) 
does not match the recordsize of an existing file. 


User Action. Change the value in the RECORDSIZE clause. 
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CANCHAARR, Cannot change array dimensions (ERR=240) 


Explanation. The program attempts to redimension an array to 
a different number of dimensions. 


User Action. Change the arrays dimensions in the DIM or MAT 
statement. 


CANFINFIL, Can’t find file or account (ERR=5) 


Explanation. The specified file or directory is not present on the 
device. 


User Action. Supply a valid file specification. 


CANINVMAT, Can’t invert matrix (ERR=56) 


Explanation. The program attempts to invert a single-dimension 
matrix. 


User Action. Supply a matrix of the proper form for inversion. 


CANOPEFIL, Cannot open file (ERR=162) 


Explanation. The program attempts to open a file that cannot be 
opened. 


User Action. Use VMSSTATUS to determine the RMS failure 
that caused the error. 


CLIPONOFF, Clipping must be set to ON or OFF (ERR=259) 


Explanation. Valid strings for the SET CLIP statement are “ON” 
and “OFF”. 


User Action. Change the string to either “ON” or “OFF”. 


COLNOTCON, Color indices are not contiguous (ERR=261) 


Explanation. The color indices on the device you are using are 
not contiguous. 


User Action. Unlike most devices, all color indices between zero 
and the number returned by the ASK MAX COLOR statement, 
are not available on this device. 
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COONOTNDC, Coordinates are not within NDC space (ERR=273) 


Explanation. The boundaries of NDC space are 0,1,0,1; coordi- 
nates must be within this range. 


User Action. Supply coordinates with values between 0 

and 1. Make sure that the minimum value of x is less than the 
maximum value of x and that the minimum value of y is less 
than the maximum value of y. 


CORFILSTR, Corrupted file structure (ERR=29) 
Explanation. RMS has detected an invalid file structure on disk. 


User Action. See your system manager. 


DATFORERR, Data format error (ERR=50) 


Explanation. The program specifies a data type in a statement 
that does not agree with the value supplied or invalid data was 
used in string arithmetic. 


User Action. Change the statement or supply data of the correct 
type. 


DATOVERF, data overflow (ERR = 289) 


Explanation. The keystroke retrieved by the INKEY$ func- 
tion caused the type-ahead buffer to overflow or the terminal 
attempted to send a valid ANSI escape sequence that did not 
correspond to a keystroke. 


User Action. Specify the DCL command SET 
TERMINAL/HOSTSYNC, before using the INKEY$ function. 
This command will prevent the type-ahead buffer from 
overflowing. 


DATTYPERR, Data type error (ERR=101) 


Explanation. The program attempts to access a parameter passed 
BY DESC (by descriptor), and the descriptor contains an incorrect 
data type. This error cannot be trapped with a VAX BASIC 
error handler unless the program contains OPTION HANDLE = 
FATAL. 


User Action. Check the program code that created the passed 
parameter and make sure it creates a parameter of correct data 


type. 
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DEADLOCK, Detected deadlock while waiting for GET or FIND 


(ERR=193) 


Explanation. The record your program is trying to access is 
currently locked on another channel or by another process. 
Simultaneously, your program has locked a record that the other 
user cannot access. The deadlock cannot be resolved. 


User Action. Possible solutions include: 


e Use the FREE statement to unlock all locked records 
e Use GET...REGARDLESS if read access is sufficient 


DECERR, DECIMAL error or overflow (ERR=181) 


Explanation. The result of a DECIMAL expression is greater 
than or requires more precision than can be contained in the 
variable. 


User Action. Reduce the magnitude of the expression or increase 
the allowed digits in the DECIMAL variable. 


User Action. Check program logic or trap the error in an error 
handler. 


DEVHUNWRI, Device hung or write locked (ERR=14) 


Explanation. The program attempted an operation to a hardware 
device that is not functioning properly or is protected against 
writing. 

User Action. Check the device on which the operation is per- 
formed. 


DEVINMET, Device is an input metafile (ERR=270) 


Explanation. The operation cannot be performed on an input 
metafile (device type 3). 


User Action. Specify the device id for a device other than an 
input metafile. 


DEVNOTOPE, Device is not open (ERR=268) 
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Explanation. The device has not been identified in an OPEN ... 
FOR GRAPHICS statement. 


User Action. Specify the device id number in an OPEN ... FOR 
GRAPHICS statement. 


DEVOPEINC, Device and operation are incompatible (ERR=272) 


Explanation. The operation you requested cannot be performed 
on the specified device. For example, output cannot be displayed 
on a device that is for input only. 


User Action. Specify the device id for a device with the appro- 
priate compatibility. Device types are listed in Programming with 
VAX BASIC Graphics. 


DEVOUTMET, Device is an output metafile (ERR=269) 


Explanation. The specified device is an output metafile (device 
type 2). 

User Action. Specify the device id for a device other than an 
output metafile. 


DEVTYPNOT, Device type is not supported (ERR=267) 


Explanation. The specified device type is not supported by VAX 
GKS. 


User Action. Specify an alternative device type. Standard 
supported device types are listed in Programming with VAX 
BASIC Graphics and in the VAX GKS documentation. Verify with 
your system manager that support for the specified device has 
been installed. Also, verify that the VAX GKS startup command 
procedure has properly executed. 


DIFUSELON, Differing use of LONG/WORD or SINGLE/DOUBLE 
qualifiers (ERR=229) 


Explanation. The main and subprograms were compiled with 
different LONG/WORD modes. This error cannot be trapped 
with a VAX BASIC error handler unless the program contains 
OPTION HANDLE = FATAL. 


User Action. Recompile one of the programs with the same 
qualifier as the other. 
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DIMOUTRAN, Dimension number out of range (ERR=195) 


Explanation. The upper or lower bound of the specified dimen- 
sion cannot be returned because the array has fewer dimensions 
than the one requested. 


User Action. Change the dimensions specified with the 
LBOUND or UBOUND function. 


DIRERR, Directive error (ERR=253) 
Explanation. A system service call resulted in an error. 


User Action. See the VAX/VMS I/O Reference Volume or the 
VAX Record Management Services Reference Manual. 


DIVBY_ZER, Division by 0 (ERR=61) 
Explanation. The program attempts to divide a value by zero. 


User Action. Check program logic and change the attempted 
division or trap the error in an error handler. 


DUPKEYDET, Duplicate key detected (ERR=134) 


Explanation. In a PUT operation to an indexed file, a duplicate 
key was specified, and DUPLICATES was not specified when the 
file was created. 


User Action. Change the duplicate key, or re-create the file 
specifying DUPLICATES for that key. 


ECHTYPNOT, Prompt/echo type not supported (ERR=256) 


Explanation. The specified prompt or echo type is invalid. VAX 
BASIC supports only the default prompt and echo types. 


User Action. Do not change the prompt or echo type. If you do 
so, you should continue to use direct calls to VAX GKS routines 
rather than use VAX BASIC input statements. 


ENDFILDEV, End of file on device (ERR=11) 


Explanation. The program attempted to read data beyond the 
end of the file. 


User Action. None. The program can trap this error in an error 
handler. 
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ENTPOINOT, Entered points not within a transformation (ERR=285) 


Explanation. Input points are not within the viewport of a 
defined transformation. 


User Action. Issue a warning to the user to input points within 
the defined area. Alternatively, you can change at least one 
transformation to include the viewport area not defined. At the 
start of program execution, transformation 1 includes all of NDC 
space. Optionally, you can define one transformation to cover 
the default viewport. 


ERRFILCOR, Error on OPEN - file corrupted (ERR=178) 


Explanation. The program attempted to open an invalid struc- 
ture on disk. 


User Action. See your system manager. 


ERRTRANEE, ERROR trap needs RESUME (ERR=246) 


Explanation. An error handler attempts to execute an END, 
END SUB, END FUNCTION, SUBEND, FUNCTIONEND, or 
FNEND statement without first executing a RESUME statement. 
This error cannot be trapped with a VAX BASIC error handler 
unless the program contains OPTION HANDLE = FATAL. 


User Action. Change the program logic so that the error han- 
dler executes a RESUME statement before executing an END, 
END SUB, END DEF, SUBEND, FUNCTIONEND, or FNEND 
statement. 


FATSYSIO_, Fatal system I/O failure (ERR=12) 


Explanation. An I/O error has occurred in: (1) the system or 
(2) Record Management Services. The last operation will not be 
completed. 


User Action. See the VAX/VMS System Messages and Recovery 
Procedures Reference Manual for RMS errors or retry the opera- 
tion. Use VMSSTATUS to return the VAX/VMS condition code 
that caused the error. 
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FIEOVEBUF, FIELD overflows buffer (ERR=63) 


Explanation. A FIELD statement attempts to access more data 
than exists in the specified buffer. 


User Action. Change the FIELD statement to match the buffer’s 
size, or increase the buffer’s size. 


FILACPFAI, FILE ACP failure (ERR=252) 


Explanation. The operating system’s file handler reported an 
error to RMS. 


User Action. See the VAX/VMS I/O Reference Volume or the 
VAX Record Management Services Reference Manual. 


FILATTNOT, File attributes not matched (ERR=160) 


Explanation. The following attributes in the OPEN statement do 
not match the corresponding attributes of the target file: 


e ORGANIZATION 
e BUCKETSIZE 
e BLOCKSIZE 


¢ Key number, size, position, or attributes (CHANGES and 
DUPLICATES) 


e Record format 


User Action. Change the OPEN statement attributes to match 
those of the file or remove the clause. 


FILEXPDAT, File expiration date not yet reached (ERR=174) 


Explanation. The program attempted to delete a file before the 
file’s expiration date was reached. 


User Action. Change the file’s expiration date. 


FILIS_LOC, File is locked (ERR=138) 
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Explanation. The program does not allow shared access, and 
attempts to access a file that has been locked by another user or 
by the system. 


User Action. Change the OPEN statement to allow shared 
access or wait until the file is released by other users. 


FLOPOIERR, Floating point error or overflow (ERR=48) 


Explanation. A program operation resulted in a floating-point 
number with absolute value outside the allowable range for that 
data type. 


User Action. Check program logic or trap the error in an error 
handler. 


FNEWITFUN, FNEND without function call (ERR=73) 


Explanation. The program executes an END DEF or FNEND 
statement before executing a function call. This error cannot be 
trapped with a VAX BASIC error handler unless the program 
contains OPTION HANDLE = FATAL. 


User Action. Check program logic to make sure that END DEF 
or FNEND statements are executed only in multi-line DEFs or 
remove the END DEF or FNEND statement. 


GKSNOTINS, VAX GKS is not installed (ERR=226) 


Explanation. Graphics statements are not operational when VAX 
GKS is not installed. 


User Action. See your system manager. 


ILLALLCLA, Illegal ALLOW clause (ERR=168) 


Explanation. The value specified for the ALLOW clause 
(sharing) on the OPEN statement is illegal for the type of file 
organization. 


User Action. Change the ALLOW clause argument. 


ILLARGLOG, Illegal argument in LOG (ERR=53) 


Explanation. The program contains a negative or zero argument 
to the LOG or LOG10 function. 


User Action. Supply an argument in the valid range. 
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ILLARESTY, Illegal area style (ERR=262) 
Explanation. Area style must be one of the following: 
e SOLID (the default) 


e HOLLOW 
e HATCH 
e PATTERN 


User Action. Specify a valid area style for the device. 


ILLBYTCOU, Illegal byte count for 1/O (ERR=31) 


Explanation. A PRINT or INPUT list invoked a function that 
closed an I/O channel. 


User Action. Change the function so that it does not close the 
I/O channel. 


ILLCNTCLA, Illegal count clause (ERR=290) 


Explanation. In a graphics statement, you specified a COUNT 
clause with a numeric value which exceeds the size of the array. 


User Action. Specify a numeric value which is less than or equal 
to the size of the array. 


ILLCOLIND, Illegal color index (ERR=280) 


Explanation. The index you specified is not supported by the 
device. 


User Action. Specify a valid color index. The valid range of 
indices for the device is from 0 to the value retrieved by the ASK 
MAX COLOR statement. 


ILLCOLMIX, Illegal color mix (ERR-291) 


Explanation. The color mix value specified on the SET COLOR 
MIX statement is outside the range of 0 to 1. 


User Action. Specify a value between 0 and 1. 
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ILLDEVID, Illegal device identification number (ERR=266) 


Explanation: The device identification number is beyond the 
valid range of 0 through 255. 


User Action: Specify a device identification number between 0 
and 255. 


ILLDEVNAM, Illegal device name in OPEN (ERR=292) 


Explanation: An explicit or implicit OPEN...FOR GRAPHICS 
statement contains an illegal device name for the device type 
being used. Possible causes include: 

e Specifying a device that does not exist on the system 

¢ Specifying a logical name that is not defined 


e¢ Specifying a file name that does not exist when the device 
type is for an input metafile 


¢ Specifying a file name for a device type that requires a VMS 
physical device name 


User Action: Specify an appropriate device name. 


ILLECHARE, Illegal echo area (ERR=283) 
Explanation: The specified echo area boundaries are invalid. 


User Action: Specify echo area boundaries within the device 
viewport. 


ILLEXIDEF, Illegal exit from DEF* (ERR=245) 


Explanation: A multi-line DEF* contains a branch to an END, 

END SUB, END DEF, SUBEND, or FUNCTIONEND statement. 
This error cannot be trapped with a VAX BASIC error handler 

unless the program contains OPTION HANDLE = FATAL. 


User Action: Change the program logic so that the program 
executes the multi-line function’s END DEF or FNEND statement 
before executing the END, END SUB, END DEF, SUBEND, or 
FUNCTIONEND statement. 
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ILLFIEVAR, Illegal FIELD variable (ERR=122) 


Explanation: A FIELDed variable is referenced after a non- 
BASIC subprogram closed the file associated with that variable. 
This error cannot be trapped with a VAX BASIC error handler 
unless the program contains OPTION HANDLE = SEVERE. 


User Action: Check program logic; do not reference the variable 
after the file has been closed. 


ILLFILNAM, Illegal file name (ERR=2) 


Explanation: A file name is: (1) too long, (2) incorrectly format- 
ted, or (3) contains embedded blanks or invalid characters. 


User Action: Supply a valid file specification. 


ILLILLACC, Illegal or illogical access (ERR=136) 
Explanation: The requested access is impossible because: 


e The attempted record operation and the ACCESS clause in 
the OPEN statement are incompatible. 
e The ACCESS clause is inconsistent with the file organization. 


e ACCESS READ or APPEND was specified when the file was 
created. 


User Action: Change the ACCESS clause. 


ILLINIVAL, Illegal initial value (ERR=284) 


Explanation: The current initial value specified on the SET 
INITIAL VALUE or LOCATE VALUE statement is beyond the 
range of possible values. 


User Action: Specify an initial value within the default range 
(0 through 1) or within the alternative range you optionally 
specified, or change the range limits. 


ILLIO_CHA, Illegal I/O channel (ERR=46) 


Explanation: The program specified an I/O channel outside the 
legal range. 


User Action: Specify I/O channels in the range 1 to 99, inclusive 
or one returned from LIB§GET_LUN. 
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ILLKEYATT, Illegal key attributes (ERR=137) 


Explanation. The program specified CHANGES for the primary 
key. 


User Action. Remove the CHANGES specification from the 
primary key. You can specify CHANGES only for alternate keys. 


ILLLINSIZ, Illegal line size (ERR=275) 
Explanation. The specified line size is less than or equal to zero. 


User Action. Specify a line size value greater than zero. 


ILLLINSTY, Illegal line style number (ERR=274) 


Explanation. The specified line style number is less than or 
equal to zero. 


User Action. Specify a valid line style value greater than zero. 


ILLNETOPE, Illegal network operation (ERR=190) 


Explanation. The program tries to mix GET and PUT operations, 
or PRINT and INPUT operations, on a remote terminal-format 
file. 


User Action. Change the file organization when opening the file 
to be sequential variable. 


ILLNUM, Illegal number (ERR=52) 


Explanation. A value supplied to a numeric variable is incorrect, 
for example “ABC” and “1..2” are illegal numbers. 


User Action. Supply numeric values of the correct form. 
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ILLOPE, Illegal operation (ERR=141) 


Explanation. The program attempts to: 


DELETE a record in a sequential file 

UPDATE a record on a magtape file 

Rewind a process-permanent file 

DELETE a record in a read-only file 

Assign a value to a virtual array element in a read-only file 
Perform a MARGIN operation on VIRTUAL file 


Transpose a matrix, or perform a matrix multiplication, with 
the same array as source and destination 


Perform an invalid operation on a VIRTUAL file, for exam- 
ple, using GET and PUT on a VIRTUAL file, then attempting 
to reference a virtual array dimensioned on that file 


User Action. Change the illegal operation. 


ILLPICOPE, Illegal picture operation (ERR=258) 
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Explanation. The program attempts to change a transformation 
within a picture definition. The following statements are invalid 
within pictures and within routines that are called by pictures: 


SET WINDOW 

SET VIEWPORT 

SET DEVICE WINDOW 
SET DEVICE VIEWPORT 
SET TRANSFORMATION 
SET INPUT PRIORITY 
SET CLIP 


User Action. Remove any invalid statements from the picture 
definition. Set the boundaries for windows and viewports before 
a picture is invoked. 


ILLPOISTY, Illegal point style number (ERR=276) 


Explanation. The specified point style is less than or equal to 
zero. 


User Action. Specify a valid point style greater than or equal to 
zero. 


ILLRECACC, Illogical record accessing (ERR=152) 


Explanation. The program attempts to perform an operation that 
is invalid for the specified file type, for example, a random access 
on a sequential file. 


User Action. Supply a valid operation for that file type or 
change the file type. 


ILLRECFIL, Illegal record on file (ERR=142) 
Explanation. A record contains an invalid byte count field. 


User Action. Use the DCL command DUMP to check the file for 
possible bad data. 


ILLRECLOC, Illegal record locking (ERR=187) 


Explanation. The program contains an ALLOW clause on a 
GET statement and the file was not opened with the UNLOCK 
EXPLICIT clause. This error cannot be trapped with a VAX 
BASIC error handler unless the program contains OPTION 
HANDLE = FATAL. 


User Action. Either remove the ALLOW clause from the GET 
statement or use the EXPLICIT UNLOCK clause in the OPEN 
statement. 


ILLRESSUB, Illegal RESUME to subroutine (ERR=247) 


Explanation. While in an error handler activated by an ON 
ERROR GO BACK, the error handler attempts to RESUME 
without a line number. This error cannot be trapped with a 
VAX BASIC error handler unless the program contains OPTION 
HANDLE = FATAL. 


User Action. None; you cannot specify the RESUME statement 
without a line number in any program module except in the 
program module containing the error handler. 
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ILLSTYIND, Illegal area style index (ERR=279) 


Explanation. The specified area style index is less than or equal 
to zero. 


User Action. Specify a valid area style index greater than zero. 


ILLSWIUSA, Illegal switch usage (ERR=67) 
Explanation. The program attempts an illegal SYS call. 


User Action. See the appropriate RSTS/E SYS call 
documentation. 


ILLSYSUSA, Illegal SYS usage( ) (ERR=18) 
Explanation. The program attempted an illegal SYS call. 


User Action. See the appropriate RSTS/E SYS call 
documentation. 


ILLTEXHEI, Illegal text height (ERR=278) 
Explanation. The text height is less than or equal to zero. 


User Action. Specify a text height greater than zero. 


ILLTEXJUS, Illegal text justification (ERR=263) 
Explanation. The specified text justification factor is invalid. 


User Action. See Programming with VAX BASIC Graphics for 
valid justification values. Specify valid values. 


ILLTEXPAT, Illegal text path (ERR=265) 
Explanation. The specified text path is invalid. 
User Action. Specify a valid text path. Valid text path values 


are: 
e RIGHT (the default) 
e LEFT 

e UP 

¢ DOWN 
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ILLTEXPRE, Illegal text precision (ERR=264) 
Explanation. The specified precision string is invalid. 


User Action. Valid precision values are: “STROKE” for software 
fonts, “STRING” and “CHAR” for hardware fonts. Specify a 
valid string for the precision value. 


ILLTEXRAT, Illegal text width-to-height ratio (ERR=276) 


Explanation. The specified width-to-height ratio is less than or 
equal to zero. 


User Action. Specify a width-to-height ratio greater than zero. 


ILLTFFOPE, Illegal terminal-format file operation (ERR=191) 


Explanation. The program specifies a GETRFA function on a 
terminal-format file. 


User Action. Change the file organization when opening the file 
to be sequential variable. 


ILLTRANUM, Illegal transformation number (ERR=257) 


Explanation. The specified tranformation number is less than 1 
or greater than 255. 


User Action. Specify a transformation number between 1 and 
255. 
ILLUSADEYV, Illegal usage for device (ERR=133) 


Explanation. The requested operation cannot be performed 
because: 

¢ The device specification contains illegal syntax 

e The specified device does not exist on your system 


e The specified device is inappropriate for the requested 
operation (for example, an indexed file access on magnetic 
tape) 


User Action. Supply the correct device type. 
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ILLWAIVAL, Illegal wait value (ERR=192) 


Explanation. The specified integer expression on the WAIT 
clause is less than zero or greater than 255. 


User Action. Specify an integer expression whose value is 0 
through 255. 


IMASQUROO, Imaginary square roots (ERR=54) 


Explanation. An argument to the SQR function is negative. 


User Action. Supply arguments to the SQR function that are 
greater than or equal to zero. 


IMPERRHAN, improper error handling (ERR=186) 


Explanation. After an error has occurred, a program’s error 
handler calls another program unit, and the called program unit 
executes an ON ERROR GO BACK statement before clearing the 
error with a RESUME statement. This error cannot be trapped 
with a VAX BASIC error handler unless the program contains 
OPTION HANDLE = FATAL. 


User Action. Change the program logic so that the called 
program clears the error condition before executing the ON 
ERROR GO BACK statement. 


INDNOTFUL, Index not fully optimized (ERR=170) 


INTERR, 
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Explanation. A record was successfully written to an INDEXED 
file; however, the alternate key path was not optimized. This 
slows record access. 


User Action. Delete the record and rewrite it. 


Integer error (ERR=51) 


Explanation. The program contains an integer whose absolute 
value is greater than 255 in BYTE mode, 32767 in WORD mode, 
or 2147483647 in LONG mode. 


User Action. Use an integer in the valid range for specified data 
type. 


INVCHASTR, Invalid character in string (ERR = 287) 


Explanation. The program attempts to output a string that 
contains an invalid character. 


User Action. Remove the invalid character from the string. 


INVFILOPT, Invalid file options (ERR=139) 


Explanation. The program has specified invalid file options in 
the OPEN statement. 


User Action. Change the invalid file options. 


INVKEYREF, Invalid key of reference (ERR=144) 


Explanation. The program attempts to perform a GET, FIND, 
or RESTORE on an INDEXED file using an invalid KEY, for 
example, an alternate KEY that does not exist for the file that 
was opened. 


User Action. Use a valid KEY in the GET, FIND, or RESTORE 
statement. 


INVRFAFIE, Invalid RFA field (ERR=173) 


Explanation. During a FIND or GET by RFA, an invalid record’s 
file address was specified. 


User Action. Supply a correct RFA field. 


IO_CHAALR, I/O channel already open (ERR=7) 


Explanation. The program attempted to open a channel that had 
already been opened and the implicit close failed. 


User Action. Submit an SPR. 


IO_CHANOT, I/O channel not open (ERR=9) 


Explanation. The program attempted to perform an I/O opera- 
tion before opening the channel. 


User Action. Open the channel before attempting an 1/O 
operation to it. 
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KEYFIEBEY, Key field beyond end of record (ERR=151) 


Explanation. The position given for the key field exceeds the 
maximum size of the record. 


User Action. Specify a key field within the record. 
KEYLARTHA, Key larger than record (ERR=159) 


Explanation. The key specification exceeds the maximum record 
size. 


User Action. Reduce the size of the key specification. 


KEYNOTCHA, Key not changeable (ERR=130) 


Explanation. An UPDATE statement attempted to change a 
key field that did not have CHANGES specified in the OPEN 
statement. 


User Action. Remove the changed key field in the UPDATE 
statement or specify CHANGES for that key field in the OPEN 
statement. Note that the primary key cannot be changed and 
that you cannot specify CHANGES when you open an existing 
file if the OPEN statement that created the file did not specify 
CHANGES. 


KEYSIZTOO, Key size too large (ERR=145) 


Explanation. The key length on a GET or FIND is either zero or 
larger than the key length defined for the target record. 


User Action. Change the key specification in the GET or FIND 
statement. 


KEYWAIEXH, Keyboard wait exhausted (ERR=15) 


Explanation. No input was received during the execution of an 
INPUT, LINPUT, or INPUT LINE statement that was preceded 
by a WAIT statement or INKEY$ timeout value. 


User Action. None; you must supply input within the specified 
time. 
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MATDIMERKR, Matrix dimension error (ERR=124) 
Explanation. The program: 


e Attempts to assign more than two dimensions to an array 


e Attempts to reference an array with fewer or more subscripts 
than there are dimensions in the array 


e Attempts to redimension an array that cannot be redimen- 
sioned 


This error cannot be trapped with a VAX BASIC error handler 
unless the program contains OPTION HANDLE = FATAL. 


User Action. Change the number of array subscripts. Reference 
the array using the correct number of dimensions, or change the 
array so that it can be redimensioned. 


MAXMEMEXC, Maximum memory exceeded (ERR=126) 


Explanation. The program has insufficient string and I/O buffer 
space because: (1) its allowable memory size has been exceeded, 
or (2) the system’s maximum memory capacity has been reached. 
This error cannot be trapped with a VAX BASIC error handler 
unless the program contains OPTION HANDLE = FATAL. 


User Action. Reduce the amount of string or I/O buffer space, 
or split the program into two or more programs. 
MEMMANVIO, Memory management violation (ERR=35) 


Explanation. The program attempted to read or write to a 
memory location to which it was not allowed access. This error 
cannot be trapped with a VAX BASIC error handler unless the 
program contains OPTION HANDLE = FATAL. 


User Action. If the program was compiled with /NOCHECK, 
it may be exceeding an array bound; recompile with /CHECK. 
Otherwise, check program logic. 

MISSPEFEA, Missing special feature (ERR=66) 


Explanation. The program attempts to use an unavailable SYS 
call. 


User Action. See the appropriate RSTS/E SYS call 
documentation. 


Run-Time Error Messages B-23 


MOVOVEBUF, Move overflows buffer (ERR=161) 


Explanation. In a MOVE statement, the combined length of 
elements in the I/O list exceeds the size of the record just read 
or the size of the buffer. 


User Action. Reduce the size of the I/O list or increase the file’s 
RECORDSIZE. 


NEGFILSTR, Negative fill or string length (ERR=166) 


Explanation. A MOVE statement I/O list contains a FILL item 
or string length with a negative value. 


User Action. Change the FILL item or string length value to be 
greater than or equal to zero. 


NEGZERTAB, negative or zero TAB (ERR=176) 


Explanation. The program attempted a zero or negative TAB. 
This error is signaled only for programs compiled with the 
/ANSI_STANDARD qualifier. 


User Action. Change the argument to the TAB statement. 
NETOPERR, network operation error (ERR=182) 


Explanation. The program attempts to perform an invalid 
network operation, or the network software failed during a 
network operation. 


User Action. Take action based on the associated error 
messages. 


NODNAMERR, Node name error (ERR=175) 


Explanation. A file specification’s node name contains a syntax 
error. 


User Action. Supply a valid node name. 


NOTBASIC, Not a BASIC error (ERR=194) 


Explanation. The error is not a VAX BASIC error and is not 
mapped to an alternative VAX BASIC error message. 


User Action. Use RMSSTATUS or VMSSTATUS to access the 
text of the error message. 
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NOTENDFIL, Not at end of file (ERR=149) 


Explanation. The program attempted a PUT operation: (1) on 
a sequential or relative file before the last record, or (2) without 
opening the file for WRITE access. 


User Action. OPEN a sequential or relative file with ACCESS 
APPEND or OPEN the file with ACCESS WRITE. 


NOTENODAT, Not enough data in record (ERR=59) 


Explanation. An INPUT statement did not find enough data in 
one line to satisfy all the specified variables. 


User Action. Supply enough data in the record or reduce the 
number of specified variables. 


NOTIMP, Not implemented (ERR=250) 


Explanation. The program attempted to use a feature that does 
not exist in this version of VAX BASIC for example, TIME(4%). 


User Action. Do not use the feature. 


NOTRANACC, Not a random access device (ERR=64) 


Explanation. The program attempts a random access on a device 
that does not allow such access; for example, a PUT with a 
record number to a magtape file. 


User Action. Make the access sequential instead of random or 
use a suitable I/O device. 


NO_CURREC, No current record (ERR=131) 


Explanation. The program attempts a DELETE or UPDATE 
when the previous GET or FIND failed, or no previous GET or 
FIND was done. 


User Action. Correct the cause of failure for the previous GET 
or FIND, or make sure a GET or FIND was done, then retry the 
operation. 


NO_PRIKEY, No primary key specified (ERR=150) 


Explanation. The program attempts to create an INDEXED file 
without specifying a PRIMARY KEY value. 


User Action. Specify a PRIMARY KEY. 
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NO_ROOUSE, No room for user on device (ERR=4) 


Explanation. No user storage space exists on the specified 


device. 


User Action. Delete files that are no longer needed. 


NUMCOOINS, Number of coordinates insufficient (ERR=281) 


Explanation. Insufficient coordinates are provided. A GRAPH 
POINTS statement requires the coordinates for at least one point. 
A GRAPH LINES statement requires a minimum of two points. 
A GRAPH AREA statement requires a minimum of three points. 


User Action. Supply an adequate number of points. 


ONEOR_TWO, One or two dimensions only (ERR=102) 


Explanation. The program contains a MAT statement that 
attempts to assign more than two dimensions to an array. This 
error cannot be trapped with a VAX BASIC error handler unless 
the program contains OPTION HANDLE = FATAL. 


User Action. Change the number of dimensions in the MAT 
statement to one or two. 


ON_—STAOUT, ON statement out of range (ERR=58) 


Explanation. The index value in an ON GOTO or ON GOSUB 
statement is less than one or greater than the number of line 
numbers in the list. 


User Action. Check program logic to make sure that the index 
value is greater than or equal to one, and less than or equal to 
the number of line numbers in the ON GOTO or ON GOSUB 


statement. 


OUTOF_DAT, Out of data (ERR=57) 
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Explanation. A READ statement requested additional data from 
an exhausted DATA list. 


User Action. Remove the READ statement, reduce the number 
of variables in the READ statement, or supply more DATA items. 


PRIKEYOUT, Primary key out of sequence (ERR=158) 


Explanation: RMS has detected an error in a sequential PUT to 
an INDEXED file. 


User Action: Change the PUT statement. If this does not work, 
the file is corrupted and you cannot do anything. 


PRIUSIFOR, PRINT-USING format error (ERR=116) 


Explanation: The program contains a PRINT USING statement 
with an invalid format string. 


User Action: Change the PRINT USING format string. 
PROC_TRA, Programmable *C trap (ERR=28) 


Explanation: A CTRL/C was typed at the controlling terminal. 


User Action: None; however, you can trap this error with an 
error handler. 


PROLOSSOR, Internal error in VAX BASIC Run-Time Library. Please submit 
an SPR. (ERR=103) 


Explanation: A consistency check in the VAX BASIC run-time 
support failed. Program execution is aborted. This error cannot 
be trapped with a VAX BASIC error handler unless the program 
contains OPTION HANDLE = FATAL. 


User Action: This error should never occur. Submit a Software 
Performance Report. 


PROVIO, Protection violation (ERR=10) 


Explanation: The program attempted to read or write to a file 
whose protection code did not allow the operation. 


User Action: Use a different file or change the file’s protection 
code or the attempted operation. 


RECALREXI, Record already exists (ERR=153) 


Explanation: An attempted random access PUT on a relative file 
has encountered a pre-existing record. 


User Action: Specify a different record number for the PUT or 
delete the record. 
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RECATTNOT, Record attributes not matched (ERR=228) 


Explanation: A RECORDTYPE clause specifies record attributes 
that do not match those of the file. 


User Action: Change the RECORDTYPE attribute to match that 
of the file. 


RECBUCLOC, Record /bucket locked (ERR=154) 


Explanation: The program attempts to access a record or bucket 
that has been locked by another program. 


User Action: Retry the operation. 


RECFILTOO, Record on file too big (ERR=157) 
Explanation: The specified record is longer than the input buffer. 


User Action: Increase the input buffer’s size. 


RECHASBEE, Record has been deleted (ERR=132) 


Explanation: A record previously located by its Record File 
Address (RFA) has been deleted. 


User Action: None. 


RECNOTFOU, Record not found (ERR=155) 


Explanation: A random access GET or FIND was attempted on 
a deleted or nonexistent record. 


User Action: None. 


RECNUMEXC, RECORD number exceeds maximum (ERR=147) 


Explanation: The specified record number exceeds the maximum 
specified for this file. 


User Action: Reduce the specified record number. The max- 
imum record number cannot be specified in VAX BASIC; it is 
either a default, or it was specified by a non-BASIC program 
when the file was created. 
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RECOVEMAP, RECORDSIZE overflows MAP buffer (ERR=185) 


Explanation: The OPEN statement specifies a RECORDSIZE 
value larger than the size of the MAP specified in the MAP 
clause. This error cannot be trapped with a VAX BASIC error 
handler unless the program contains OPTION HANDLE = 
FATAL. 


User Action: Increase the size of the MAP to match the 
RECORDSIZE value. 


REDARR, Redimensioned array (ERR=105) 


Explanation: A MAT statement attempts to redimension an 
array to have more elements than were originally dimensioned. 


User Action: Change the statement that attempts the redimen- 
sion or increase the original number elements. 


REMOVEBUF, REMAP overflows buffer (ERR=183) 


Explanation: A REMAP statement causes the variables in the 
dynamic MAP to be associated with nonexistent storage. 


User Action: Change the REMAP statement so that all variables 
are associated with the storage in the MAP. 


REMSTRNOT, REMAP string is not static (ERR=196) 


Explanation: The program referenced a string with a REMAP 
statement that was not declared in COMMON or MAP. 


User Action: Declare the string in the COMMON or MAP 
statement. 


RESNO_ERR, RESUME and no error (ERR=104) 


Explanation: The program executes a RESUME statement 
without a line number outside of the error handling routine. 
This error cannot be trapped with a VAX BASIC error handler 
unless the program contains OPTION HANDLE = FATAL. 


User Action: Check program logic to make sure that the 
RESUME statement is executed only in the error handler. 


Run-Time Error Messages B-29 


RETWITGOS, RETURN without GOSUB (ERR=72) 


Explanation: The program executes a RETURN statement before 
a GOSUB. This error cannot be trapped with a VAX BASIC 
error handler unless the program contains OPTION HANDLE = 
FATAL. 


User Action: Check program logic to make sure that RETURN 
statements are executed only in subroutines or remove the 
RETURN statement. 


RRVNOTFUL, RRV not fully updated, (ERR=171) 


Explanation: RMS wrote a record successfully, but did not 
update one or more Record Retrieval Vectors. Therefore, you 
cannot retrieve any records associated with those vectors. 


User Action: Delete the record and rewrite it. 


SCAFACINT, SCALE factor interlock (ERR=127) 


Explanation: A subprogram was compiled with a different 
SCALE factor than that of the calling program. This error cannot 
be trapped with a VAX BASIC error handler unless the program 
contains OPTION HANDLE = FATAL. 


User Action: Recompile one of the programs with a scale factor 
that matches the other. 


SIZRECINV, Size of record invalid (ERR=156) 


Explanation: The program contains a COUNT or RECORDSIZE 
specification that is invalid because: 
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COUNT equals zero 
COUNT exceeds the maximum size of the record 


COUNT conflicts with the actual size of the current record 
during a sequential file UPDATE on disk 


COUNT does not equal the recordsize for fixed format 
records 


You specified a record size in the OPEN statement that was 
unequal to the actual record size established when the file 
was created. 


July 1988 


User Action: Supply a valid COUNT value in the PUT or 
UPDATE statement, or a valid RECORDSIZE in the OPEN 
statement, whichever is applicable. 
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STO, Stop (ERR=123) 


Explanation. The program executed a STOP statement. This 
error cannot be trapped with a VAX BASIC error handler unless 
the program contains OPTION HANDLE = INFO or a greater 
severity. 


User Action. Continue execution by typing CONTINUE or 
terminate execution by typing EXIT. 


STRLENZER, string length is zero (ERR = 288) 


Explanation. A graphics statement references a null string where 
a null string is illegal. 


User Action. Adjust the string length so that it is greater than 
zero. 


STRTOOLON, String too long (ERR=227) 


Explanation. The program attempts to create a string longer 
than 65535 bytes. 


User Action. Reduce the length of the string. 


SUBOUTRAN, Subscript out of range (ERR=55) 


Explanation. The program attempts to reference an array ele- 
ment outside of the array’s dimensioned bounds. 


User Action. Check program logic to make sure that all array 
references are to elements within the array boundaries. 


TAPBOTDET, Tape BOT detected (ERR=129) 


Explanation. The program attempts a rewind or backspace 
operation on a magnetic tape that is already at the beginning of 
the file. 


User Action. Trap the error or check program logic; do not 
rewind or backspace if the magnetic tape is at the beginning of 
the file. 
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TAPNOTANS, Tape not ANSI labeled (ERR=146) 


Explanation. The program attempts to access a file-structured 
magnetic tape that does not have an ANSI label. 


User Action. Determine the magnetic tape’s format by mounting 
it with the /FOREIGN qualifier and using the DCL DUMP com- 
mand. You can then access it as a non-file-structured magnetic 
tape. 


TAPRECNOT, Tape records not ANSI (ERR=128) 


Explanation. The records in the magtape you accessed are 
neither ANSI D nor ANSI F format. 


User Action. Determine the magtape’s format by mounting 
it with the /FOREIGN qualifier and using the DCL DUMP 
command. 


TERFORFIL, Terminal format file required (ERR=164) 


Explanation. The program attempted to use PRINT #, INPUT #, 
LINPUT #, MAT INPUT #, MAT PRINT #, or PRINT USING # 
to access a RELATIVE, INDEXED, or VIRTUAL file. 


User Action. Supply a terminal-format file. 


TOOFEWARG, Too few arguments (ERR=97) 


Explanation. A function invocation, CALL, or DRAW statement 
passed fewer arguments than were defined in the function, 
picture, DEF, DEF*, or subprogram. This error cannot be trapped 
with a VAX BASIC error handler unless the program contains 
OPTION HANDLE = FATAL. 


User Action. Change the number of arguments to match the 
number defined in the function or subprogram. 


TOOLITDAT, too little data in record (ERR = 189) 
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Explanation. An INPUT statement did not find enough data in 
one line to satisfy all the specified variables. This error is sig- 
naled only for programs compiled with the /ANSI_STANDARD 
qualifier. 


User Action. Supply enough data in the record, or reduce the 
number of specified variables. 


TOOMANARG, Too many arguments (ERR=89) 


Explanation: A function invocation, CALL, or DRAW statement 
passed more arguments than were expected. This error cannot 
be trapped with a VAX BASIC error handler unless the program 
contains OPTION HANDLE = FATAL. 


User Action: Reduce the number of arguments. A SUB or 
FUNCTION subprogram can pass a maximum of 255 arguments; 
a DEF function call can pass a maximum of eight arguments. 


TOOMUCDAT, too much data in record (ERR=177) 


Explanation: The user has given too many items in response 
to the INPUT statement. This error is only signalled for ANSI 
INPUT. 


User Action: Supply the correct number of items to the INPUT 
statement or change the INPUT statement. 


TRANOTDIF, Transformation numbers are not different (ERR=260) 


Explanation: The same transformation number is used twice in 
the SET INPUT PRIORITY statement. 


User Action: Specify two different transformations in the SET 
INPUT PRIORITY statement. 


UNEFILDAT, unexpired file date (ERR=179) 


Explanation: The program attempts to delete a file whose 
expiration date has not yet passed. 


User Action: None. 


UNINUMNOT, Unit number is not defined for the device (ERR=282) 


Explanation: The specified unit is a method that is not sup- 
ported by the device. (The default unit is 1.) 


User Action: Verify the supported units for the device and 
specify a valid unit. 
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UNKGKSERR, Unknown GKS error (ERR=286) 


Explanation: A graphics error has ocurred that is not mapped to 
a VAX BASIC error message. 


User Action: Use VMSSTATUS to access the text of the 
VAX GKS error message. 


USEABOINP, User aborted input, locate point cancelled (ERR=293) 


Explanation: ERROR - The middle mouse button was pressed 
during the execution of a graphics input statement that uses a 
mouse to enter points (e.g. LOCATE POINT). The pressing of 
the middle mouse button aborts the graphics input statement in 
progress and the data in the variables used for the graphics input 
statement is unchanged. 


The pressing of the middle mouse button during a graphics input 
statement is analogous to typing CTRL/Z at a regular INPUT 
statement. 


User Action: None. The program can trap this error in an error 
handler and attempt the input statement again if so desired. 


VIRARRDIS, Virtual array not on disk (ERR=43) 


Explanation: The program attempted to reference a virtual 
array on a nondisk device, or the virtual array is not opened as 
ORGANIZATION VIRTUAL. 


User Action: Virtual arrays must be on disk; change the file 
specification in the OPEN statement for this array. Open the file 
with ORGANIZATION VIRTUAL. 


VIRARROPE, Virtual array not yet open (ERR=45) 


Explanation: The program attempted to reference a virtual array 
before opening the associated disk file. 


User Action: Open the disk file containing the virtual array 
before referencing the array. 


-VIRBUFTOO, Virtual buffer too large (ERR=42) 


Explanation: The program attempted to access a VIRTUAL file 
and the buffer size was not 512 bytes. 


User Action: Change the I/O buffer to be a multiple of 512 
bytes. 
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B.2 VAX BASIC Run-time Errors By Number 


1 BADDIRDEV, Bad directory for device 

2 ILLFILNAM, Illegal file name 

4 NO_ROOUSE, No room for user on device 
5 CANFINFIL, Can’t find file or account 

7 IO_.CHAALR, I/O channel already open 

9 IO_CHANOT, I/O channel not open 

10 PROVIO, Protection violation 

11 ENDFILDEV, End of file on device 

12 FATSYSIO_, Fatal system I/O failure 

14 DEVHUNWRI, Device hung or write locked 
15 KEYWAIEXH, Keyboard wait exhausted 

18 ILLSYSUSA, Illegal SYS( ) usage 

28 PROC__TRA, Programmable °C trap 

29 CORFILSTR, Corrupted file structure 

31 ILLBYTCOU, Illegal byte count for I/O 

35 MEMMANVIO, Memory management violation 
42 VIRBUFTOO, Virtual buffer too large 

43 VIRARRDIS, Virtual array not on disk 

45 VIRARROPE, Virtual array not yet open 

46 ILLIO_CHA, Illegal I/O channel 

48 FLOPOIERR, Floating point error or overflow 
49 ARGTOOLAR, Argument too large in EXP 
50 DATFORERR, Data format error 

51 INTERR, Integer error 

52 ILLNUM, Illegal number 

53 ILLARGLOG, Illegal argument in LOG 

54 IMASQUROO, Imaginary square roots 

55 SUBOUTRAN, Subscript out of range 
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56 
37 
58 
59 
61 
63 
64 
66 
67 
f2 
73 
88 
89 
97 
101 
102 
103 


104 
105 
116 
122 
123 
124 
126 
127 
128 
129 
130 
131 
132 


133 


CANINVMAT, Can’t invert matrix 
OUTOF_DAT, Out of data 

ON_STAOUT, ON statement out of range 
NOTENODAT, Not enough data in record 
DIVBY_ZER, Division by 0 

FIEOVEBUF, FIELD overflows buffer 
NOTRANACC, Not a random access device 
MISSPEFEA, Missing special feature 
ILLSWIUSA, Ilegal switch usage 
RETWITGOS, RETURN without GOSUB 
FNEWITFUN, FNEND without function call 
ARGDONMAT, Arguments don’t match 
TOOMANARG, Too many arguments 
TOOFEWARG, Too few arguments 
DATTYPERR, Data type error 
ONEOR_TWO, One or two dimensions only 


PROLOSSOR, Internal error in VAX Run-Time Library. 
Please submit an SPR. 


RESNO_ERR, RESUME and no error 
REDARR, Redimensioned array 
PRIUSIFOR, PRINT-USING format error 
ILLFIEVAR, Illegal FIELD variable 

STO, Stop 

MATDIMERR, Matrix dimension error 
MAXMEMEXC, Maximum memory exceeded 
SCAFACINT, SCALE factor interlock 
TAPRECNOT, Tape records not ANSI 
TAPBOTDET, Tape BOT detected 
KEYNOTCHA, Key not changeable 
NO_CURREC, No current record 
RECHASBEE, Record has been deleted 


ILLUSADEV, Illegal usage for device 


B-36 Run-Time Error Messages July 1988 


134 
136 
137 
138 
139 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 


152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
164 
166 
168 
170 


DUPKEYDET, Duplicate key detected 
ILLILLACC, Illegal or illogical access 
ILLKEYATT, Illegal key attributes 
FILIS_LOC, File is locked 

INVFILOPT, Invalid file options 

ILLOPE, Illegal operation 

ILLRECFIL, Illegal record on file 
BADRECIDE, Bad record identifier 
INVKEYREF, Invalid key of reference 
KEYSIZTOO, Key size too large 
TAPNOTANS, Tape not ANSI labeled 
RECNUMEXC, RECORD number exceeds maximum 
BADRECVAL, Bad RECORDSIZE value on OPEN 
NOTENDFIL, Not at end of file 
NO_PRIKEY, No primary key specified 
KEYFIEBEY, Key field beyond end of record 
ILLRECACC, Illogical record accessing 
RECALREXI, Record already exists 
RECBUCLOC, Record/bucket locked 
RECNOTFOU, Record not found 
SIZRECINV, Size of record invalid 
RECFILTOO, Record on file too big 
PRIKEYOUT, Primary key out of sequence 
KEYLARTHA, Key larger than record 
FILATTNOT, File attributes not matched 
MOVOVEBUF, Move overflows buffer 
CANNOT OPEN FILE 

TERFORFIL, Terminal format file required 
NEGFILSTR, Negative fill or string length 
ILLALLCLA, Illegal ALLOW clause 
INDNOTFUL, Index not fully optimized 
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171 
173 
174 
175 
176 
177 
178 
179 
181 
182 
183 
185 
186 
187 
189 
190 
191 
192 
193 
194 
195 
196 
197 
226 
227 
228 
229 
238 
239 
240 
245 


RRVNOTFUL, RRV not fully updated, 
INVRFAFIE, Invalid RFA field 

FILEXPDAT, File expiration date not yet reached 
NODNAMERR, Node name error 

NEGTABNOT, Negative TAB not allowed 
TOOMUCDAT, Too much data in record 
ERRFILCOR, Error on OPEN - file corrupted 
UNEFILDAT, Unexpired file date 

DECERR, Decimal error or overflow 
NETOPERR, Network operation error 
REMOVEBUF, REMAP overflows buffer 
RECOVEMAP, RECORDSIZE overflows MAP buffer 
IMPERRHAN, Improper error handling 
ILLRECLOC, Illegal record locking 

TOOLITDAT, Too little data in record 
ILLNETOPE, Illegal network operation 
ILLTFFOPE, Illegal terminal-format file operation 
ILLWAIVAL, Illegal wait value 

DEADLOCK, Detected deadlock while waiting for GET or FIND 
NOTBASIC, Not a BASIC error 

DIMOUTRAN, Dimension number out of range 
REMSTRNOT, REMAP string is not static 
ARRTOOSMA, Array too small 

GKSNOTINS, VAX GKS is not installed 
STRTOOLON, String too long 

RECATTNOT, Record attributes not matched 
DIFUSELON, Differing use of LONG/WORD qualifiers 
ARRMUSSAM, Arrays must be same dimension 
ARRMUSSQU, Arrays must be square 
CANCHAARR, Cannot change array dimensions 
ILLEXIDEF, Illegal exit from DEF* 
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246 
247 
250 
252 
253 
256 
207 
258 
2o7 
260 
261 
262 
263 
264 
265 
266 
267 
268 
269 
270 
272 
273 
274 
2795 
276 
277 
278 


ERRTRANEE, ERROR trap needs RESUME 
ILLRESSUB, Illegal RESUME to subroutine 

NOTIMP, Not implemented 

FILACPFAI, FILE ACP failure 

DIRERR, Directive error 

ECHTYPNOT, Prompt/echo type not supported 
ILLTRANUM, Illegal transformation number 
ILLPICOPE, Illegal picture operation 

CLIPONOFF, Clipping must be ON or OFF 
TRANOTDIF, Transformation numbers are not different 
COLNOTCON, Color indices are not contiguous 
ILLARESTY, Illegal area style 

ILLTEXJUS, Illegal text justification 

ILLTEXPRE, Illegal text precision 

ILLTEXPAT, [legal text path 

ILLDEVID, Illegal device identification number 
DEVTYPNOT, Device type is not supported 
DEVNOTOPE, Device is not open 

DEVOUTMET, Device is an output metafile 
DEVINMET, Device is an input metafile 
DEVOPEING, Device and operation are incompatible 
COONOTNDC, Coordinates are not within NDC space 
ILLLINSTY, Illegal line style number 

ILLLINSIZ, Hlegal line size 

ILLPOISTY, Illegal point style number 

ILLTEXRAT, legal text width-to-height ratio 
ILLTEXHEI, Illegal text height 
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279 
280 
281 
282 
283 
284 
285 
286 
287 
288 
289 
290 
291 
292 
293 


ILLSTYIND, Illegal area style index 

ILLCOLIND, Illegal color index 

NUMCOOINS, Number of coordinates is insufficient 
UNINUMNOT, Unit number is not defined for the device 
ILLECHARE, Illegal echo area 

ILLINIVAL, Illegal initial value 

ENTPOINOT, Entered points not within a transformation 
UNKGKSERR, Unknown GKS error 

INVCHASTR, Invalid character in string 

STRLENZER, String length is zero 

DATOVERF, Data overflow 

ILLCNTCLA, Illegal count clause 

ILLCOLMIX, Illegal color mix 

ILLDEVNAM, Illegal device name in OPEN 
USEABOINP, User aborted input, locate point cancelled 


B.3 Errors Not Generated By VAX BASIC 


The following errors cannot be generated in VAX BASIC. However, 
they can be displayed with the ERT$ function and are included for 
completeness. 


Number’ Text 


3 

6 

8 

13 
16 
17 
19 
20 
21 
ap 


?Account or device in use 
?Not a valid device 

?Device not available 

?User data error on device 
?Name or account now exists 
?Too many open files on unit 
?Disk block is interlocked 
?Pack ids don’t match 

?Disk pack is not mounted 


?Disk pack is locked out 
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Number 


23 
24 
25 
26 
27 
30 
32 
33 
34 
36 
37 
38 
39 
40 
41 
44 
47 
60 
62 
65 
68-70 
71 
74 
75 
76 
77 
78 
79 
80 
81 


Text 


?Illegal cluster size 

?Disk pack is private 

?Disk pack needs ‘cleaning’ 
?Fatal disk pack mount error 
?1/O to detached keyboard 
?Device not file-structured 
?No buffer space available 
?Odd address trap 
?Reserved instruction trap 
2SP stack overflow 

?Disk error during swap 
?Memory parity (or ECC) failure 
?Magtape select error 
?Magtape record length error 
?Non-res run-time system 
?Matrix or array too big 
?Line too long 

?Integer overflow, FOR loop 
?No run-time system 

?Illegal MAGTAPE( ) usage 
unused 

?Statement not found 
?Undefined function called 
?Illegal symbol 

?Illegal verb 

?Illegal expression 

legal mode mixing 

?Illegal IF statement 

?Illegal conditional clause 


Illegal function name 
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Number 


82 
83 
84 
85 
86 
87 
90 
91 
92 
93 
94 
95 
96 
98 
99 
100 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
117 
118 
119 
120 
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Text 


Illegal dummy variable 
?Illegal FN redefinition 

illegal line number(s) 
?Modifier error 

?Can’t compile statement 
?Expression too complicated 
%Inconsistent function usage 
Illegal DEF nesting 

?FOR without NEXT 

?NEXT without FOR 

?DEF without FNEND 
?FNEND without DEF 

?Literal string needed 

?Syntax error 

?String is needed 

?Number is needed 

% Inconsistent subscript use 
20N statement needs GOTO 
?End of statement not seen 
?What? 

?Bad line number pair 

?Not enough available memory 
?Execute only file 

?Please use the run command 
?Can’t CONTinue 

?File exists-RENAME/REPLACE 
?Matrix or array without DIM 
?Bad number in PRINT USING 
?Iilegal in immediate mode 
?PRINT-USING buffer overflow 


Number 


121 
125 
135 
140 
163 
165 
167 
169 
172 
180 
182 
184 
188 
198-225 
230 
231 
232 
233 
234 
235 
236 
237 
241 
242 
243 
244 
248 
249 
251 
254-255 
294-300 
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Text 


Illegal statement 

2Wrong math package 

?illegal usage 

?Index not initialized 

?No file name 

?Cannot position to EOF 

Illegal record format 

unused 

?Record lock failed 

?No support for operation in task 
?Network operation rejected 
?Unaligned REMAP variable 
?UNLOCK EXPLICIT requires RECORDSIZE 512 
unused 

?No fields in image 

Illegal string image 

?Null image 

Illegal numeric image 

?Numeric image for string 

?String image for numeric 

?TIME limit exceeded 

?First arg to SEG$ greater than second 
?Floating overflow 

?Floating underflow 

?CHAIN to nonexistent line number 
?Exponentiation error 

Illegal return from subroutine 
?Argument out of bounds 
?Recursive subroutine call 

unused 


unused 
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A 


% ABORT directive ® 18-11 
ABS function ® 12-2 
Addition of matrices ® 8-22 
Address expression 
with DEPOSIT debugger command ® 5-19 
with EXAMINE debugger command ® 5-18 
with SET BREAK debugger command ® 5-14 
with SET TRACE debugger command ® 5-15 
Allocation map ® 4-27 
Ampersand (&) 
in comment field ® 6-8 
Ampersand (&) continuation character ® 3-2 
ANSI-D formatted file © 20-3 
ANSI tape files 
accessing ® 20-4 
APPEND command ® 3-13 
Arrays ® 6-13, 6-15, 8-1 to 8-26 
as part of a record buffer ® 8-7 
bounds ® 8-8 . 
bounds of 
CDD ® 4-12 
CDD ® 23-7 
creating explicitly ® 8-3 to 8-7 
creating implicitly ® 8-8 to 8-9 
creating virtual array files ® 15-15 
descriptors of ® 19-9 
FORTRAN ® 21-10 
input ® 8-10 to 8-22 
matrix ® 8-1 
of fixed-length strings ® 8-7 
of RECORD instances ® 10-3 
output ® 8-10 to 8-22 
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INDEX 


Arrays (cont’d.) 
redimensioning with DIM statement ® 8-6 
referencing ® 8-3, 8-9 
sharing among program modules ® 8-7 
subscripts ® 8-1 to 8-2 
vector ® 8-1 
within a RECORD ® 10-4 
zero-based ® 8-1 
ASCII character set ®° 6-7 
ASCII function ® 12-7 
ASSIGN command ® 3-14 
Assignment of matrices ® 8-22 
Asterisk (*) 
with PRINT USING statement ® 16-10 


BASIC 
/ANALYSIS_DATA ® 4-7 
/ANSI_STANDARD ® 4-7 
ANSI Minimal BASIC ® 4-7 
/AUDIT ® 4-7, 23-5 
CDD ® 23-1 to 23-25 
/CHECK ® 4-8 
/CROSS_REFERENCE ® 4-8 
cross-reference listing ® 4-8 
/DEBUG ® 4-8 
/DECIMAL _SIZE ® 4-9 
/DEPENDENCY_DATA ® 4-9 
/DIAGNOSTICS ® 4-10 
/FLAG ® 4-10 
/INTEGER_SIZE ® 4-10 
line numbers ® 5-9 
/LINES @ 4-10 
/LISTING ® 4-10 
/MACHINE_CODE ® 4-11 
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BASIC (cont'd.) 
/OBJECT @ 4-11 
/OLD_VERSION=CDD_ARRAYS ® 23-8 
producing source listing file © 4-11 
REAL _SIZE ® 4-12 
/ROUND_DECIMAL ® 4-13 
/SCALE ® 4-13 
/SHOW ® 4-13 
/SHOW=CDD ® 23-5 
/SYNTAX_CHECK ® 4-14 
/TYPE_DEFAULT ® 4-14 
/VARIANT ® 4-14 
/WARNINGS ® 4-15 
BASIC /CROSS_REFERENCE ® 4-16, 4-25, 4-27 
BASIC/LISTING ® 4-15 
BASIC character set ® 6-7 
BASIC command ® 2-21, 4-4 
BASIC command qualifiers 
list of ® 4-6 
BASIC compiler 
functions of ® 4-4 
Block 
loop ® 11-4 
BLOCKSIZE 
with the MOUNT command ® 20-2 
Block size 
specifying ® 20-3 
Bounds 
array ® 6-15 
CDD arrays ® 4-12 
Bounds block ® 19-11 
Breakpoint ® 5-13 
Bucketsize ® 15-37 
default value ® 15-38 
Buffers 
1/0 ® 15-6 
record ® 15-6 
Built-in lexical functions 
%VARIANT directive ® 18-10 
BY DESC ® 21-2 
BY REF ® 21-2 
BYTE data type ® 6-9 
subtypes ® 6-9 
BY VALUE ® 21-3 
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C 


Call stack © 5-12 
CALL statement ® 14-10, 21-8 
implicit declarations in ® 14-10 
parameters in® 14-10 
using for FUNCTION subprograms ® 14-10 
CANCEL MODULE debugger command ® 5-23 
CANCEL SCOPE debugger command ® 5-24 
CASE 
in RECORD variants ® 10-6 
CASE block ® 11-14 
CAUSE ERROR statement ® 17-22 
CDD 
array bounds ® 4-12 
CDD (Common Data Dictionary) ® 23-1 to 24-12 
arrays ® 23-7 
CDD$TOP ® 23-4 
CDDL ® 23-2 
NAME clause ® 23-6 
STRUCTURE statement ® 23-3 
subordinate field ® 23-3 
VARIANTS OF statement ® 23-9 
data definition ® 23-3 
extracting © 23-2 
translating ® 23-3 
data types ® 23-3, 23-11 to 23-25 
character string ® 23-15 
complex ® 23-21 
decimal string ® 23-23 
fixed-point © 23-17 
floating-point © 23-20 
integer ® 23-17 
other ® 23-24 
definition ® 23-1 
dictionary directory ® 23-4 
history list entry © 23-5 
%INCLUDE %FROM %CDD directive ® 23-2 
object ® 23-4 
/OLD_VERSION=CDD_ARRAYS ® 23-8 
path name ® 23-4 to 23-5, 24-4 to 24-5 
full © 23-5 
relative ® 23-5 
variant ® 23-9 
with the RECORD statement ® 23-2 
_ CDDSTOP ® 23-4, 24-4 
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CDD definitions 
including ® 18-7, 24-4 
CDDL 
NAME clause ® 23-6 
Centered fields 
with PRINT USING statement ® 16-18 
CHANGE command ® 4-2 
Channels 
specifying with RMSSTATUS function ® 17-17 
Characters 
nonprinting ® 6-7 
Character set 
ASCII ® 6-7 
BASIC ® 6-7 
CHRS function ® 12-8 
CLOSE statement 
ending file |/O © 20-7 
ending I/O to a tape ® 20-11 
comma 
using with PRINT statement ® 7-11 
command 
See also Debugger command 
Command procedures ® 2-14 
creating and executing ® 2-16 
example of ® 2-17 
executing in batch ® 2-16 
executing interactively ® 2-16 
login ® 2-19 
command qualifiers 
with the BASIC command ® 2-21, 4-4 
with the DELETE command ® 2-11 
with the LINK command ® 2-21 
with the PRINT command ® 2-10 
with the PURGE command ® 2-11 
>ommas 
with PRINT USING statement ® 16-9 
Somment fields ® 6-8 
>omments 
entering into the BASIC environment ® 3-12 
in environment ® 3-5 
Zommon area 
defining ® 9-19 
>ommon block ® 8-7 
2ommon Data Dictionary 
See CDD 
ZSOMMON statement ® 8-7, 9-13 
sharing arrays with ® 8-7 | 
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COMMON statement (cont’d.) 

with subprograms ® 9-19 
Communication 

task-to-task ® 20-17 
Compilation 

controlling with %LET directive © 18-9 

terminating with %ABORT directive ® 18-11 
Compilation listing 

with /SHOW ® 4-13 

with %INCLUDE ® 18-8 
COMPILE command ® 3-9, 3-14 

in environment ® 3-9 
Compiler 

commands ® 3-9 to 3-30 

listing ® 4-15 

specifying options for ® 3-14 to 3-30 
Compiler directives © 18-1 

benefits of ® 18-1 

conventions of ® 18-1 

listing © 18-2 
Compiling 

/DEBUG ® 5-4 
Component 

of a RECORD ® 10-1 
Concatenation ® 9-19 
Conditional expressions 

in IF... THEN...ELSE statement ® 11-12 

in WHILE...NEXT loops ® 11-8 
Condition values ® 21-20 
Constants 

declaring ® 9-7, 9-8 

declaring externally ® 9-8 

definition of ® 9-7 

string ® 13-1 
Continuation lines 

DCL commands ® 2-4 
CONTINUE command ® 3-8, 3-18 

after CTRL/C ® 3-18 

after STOP statement ® 3-18 
CONTINUE statement ® 17-9 
Control structures ® 11-1 to 11-18 
Control! variable 

loop ® 11-4 
COS function ® 12-3 
CREATE command ® 2-16 
/CROSS_REFERENCE ® 4-16, 4-27 
CROSS_REFERENCE ® 4-25 
%CROSS directive ® 18-6 
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Cross-reference listing ® 4-25 
CTRL/C 
trapping ® 12-17 
CTRL/C trapping ® 17-18 to 17-19 
CTRL/Y 
interrupting debugger ® 5-6 
CTRL/Z 
exiting debugger ® 5-6 
CTRLC function ® 12-17, 17-18 
Currency symbol 
with PRINT USING statement ® 16-11 
Current record pointer 
resetting with RESTORE statement ® 15-32 
setting with FIND statement ® 15-16 


Data 
formatting with PRINT USING statement ® 16-1 
passing between VAX BASIC and VAX 
FORTRAN ® 21-9 
rereading with RESTORE statement ® 7-9 
sharing between modules ® 7-8 
Data blocks ® 15-1 
Data records ® 15-1 
accessing by RFA ® 15-6, 15-29 to 15-31 
access modes for ® 15-5 to 15-6 
deleting with DELETE statement ® 15-22 
determining the number transferred ® 15-36 
fields in® 15-1 
fixed-length ® 15-2 
handling locked conditions ® 15-20, 15-27 
locating ® 15-16 
moving with MOVE statement ® 15-10 
next record pointer ® 15-6 
random access by key ® 15-6 
random access by record number ® 15-6 
reading with GET statement ® 15-18 
record context of ® 15-5 to 15-6 
sequential access ® 15-6 
stream format ® 15-2 
variable-length ® 15-2 
writing with PUT statement ® 15-20 
DATA statement ® 7-7 to 7-9 
comment fields in ® 7-8 
continuing with ampersand ® 7-8 
Data structures ® 10-1 to 10-14 
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Data type and size 
setting the default © 9-5 
setting the default with qualifiers ® 9-5 
setting the default with the OPTION statement ® 
9-5 
Data type keywords 
with FILL ® 9-18 
Data type promotions 
with expressions ® 9-9 to 9-12 
Data types ® 6-9 
BYTE ®6-9 
DECIMAL ® 6-9 
definition of ® 9-2 
Floating-point ® 9-2 
INTEGER ® 6-9, 9-2 
list of © 9-2 
LONG ® 6-9 
packed decimal ® 6-9 
REAL ® 6-9 
RFA ®6-9, 9-2 
STRING ® 6-9 
subtypes ® 6-9 
table of © 9-3 
user-defined ® 10-1 
WORD ® 6-9 
DATES function ® 12-16 
DCL $STATUS ® 14-11 
DCL commands 
continuation indicator ® 2-4 
file-handling ® 2-8 
for program development ® 2-20 
rules and options ® 2-4 to 2-14 
DCL symbols 
defining ® 2-14 
Deadlock ® 15-27 
Debit and credit notation 
with PRINT USING statement ® 16-15 
DEBUG command ® 5-5 
Debugger ® 5-1 
Debugger command 
summary ® 5-26 
Debugging ® 5-1 
/DEBUG qualifier © 5-4 
DECIMAL 
variables ® 6-14 
DECIMAL data type ® 6-9 
Decimal point location 
with PRINT USING statement ® 16-6 


Decision blocks 
controlling ® 11-1 to 11-18 
Decision structures ® 11-11 to 11-16 
comparison of ® 11-11 
Declarative statements ® 6-10, 9-1 
purpose of ® 9-1 
DECLARE statement ® 8-4, 9-6 
DEF ® 12-20 to 12-27 
formal parameter list ® 12-20 
multi-line © 12-22 
recursion in® 12-22, 12-25 
transferring control into ® 12-26 
transferring control out of ® 12-26 
parameters ® 12-27 
single-line ® 12-21 
DEF* 
handling errors in® 17-21 
Default values 
changing with LOCK command ® 3-23 
examining with SHOW command ® 3-28 
in the environment ® 3-9 
specifying with /TYPE_.DEFAULT ® 4-14 
specifying with SET command ® 3-28 
DEF functions 
declaring ® 9-6 
DELETE command ® 2-10, 3-18 
with comma (,) ® 3-18 
with hyphen (-) ® 3-18 
DELETE statement ® 15-22 to 15-23 
current and next record pointers after ® 15-23 
DEPOSIT debugger command ® 5-19 
Descriptors 
array ® 19-9 
decimal scalar string ® 19-12 
dynamic string ® 19-8 
fixed-length string ® 19-8 
packed decimal string ® 19-12 
DET function ® 8-26 
Device-specific 1/O 
performing to a tape drive ® 20-8 
performing to unit record devices ® 20-8 
to disks ® 20-12 
DIF$ function 
precision of ® 12-13 
DIMENSION statement ® 8-4 to 8-6 
declarative ® 8-5 
executable ® 8-6 


Directories 


referencing ® 2-8 

setting the default © 2-6 
DIRECTORY command ® 2-8 
Directory hierarchies 

illustration of © 2-6 
Directory structure ® 2-5 
Disks 

accessing ® 20-12 

creating ® 20-12 

opening ® 20-12 

opening an existing disk file ® 20-13 
Disk unit 

allocating ® 20-12 
Display 

source code ® 5-8 
Division by zero ® 17-2 
Dynamic mapping ® 9-21, 15-8 to 15-10 
Dynamic module setting ® 5-23 
Dynamic storage ® 6-1 1 

allocating ® 9-13 
Dynamic string descriptors ® 19-8 
Dynamic strings 

concatenating ® 13-2 

modifying © 13-4 

using ® 13-2 


ECHO function ® 12-18 
EDIT$ function 
string function ® 13-19 
EDIT command ® 3-2, 3-18 
in line made ® 3-18 
with text editor ® 3-19 
EDT editor 
invoking ® 4-2 
using @ 4-1 
EDT Keypad Emulator Interface ® 4-3 
EDT text editor ® 3-2 
Elliptical references ® 10-9 
ELSE clause ® 11-12 
END FUNCTION statement ® 14-4 
specifying expression with ® 14-4 
END HANDLER statement ® 17-7 
END IF statement ® 11-12 
END SUB statement ® 14-3 
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END WHEN statement ® 17-7 
Environment ® 3-1 to 3-30 
compiling in® 3-9 
continuing program lines in ® 3-2 
creating programs in ® 3-2 to 3-5 
editing programs in ® 3-2 to 3-5 
entering comments into ® 3-12 
entering DCL commands in ® 3-13 
entering program statements in ® 3-1 
invoking ® 3-1 
running multiple program units in ® 3-3 
running programs in ® 3-2 to 3-5 
ERL function ® 17-14, 17-15 
ERN$ function ® 17-15 
ERR function ® 17-13 
Error conditions 
with PRINT USING statement ® 16-20 
Error handlers 
debugging ® 17-22 
user-written® 17-2 to 17-23 
Error handling ® 17-1 to 17-26 
default ® 17-1 to 17-2 
Error messages 
compile-time ® A-1 
run-time ® B-1 
Errors 
forcing ® 17-22 
handling in DEF*s ® 17-21 
handling in functions ® 17-21 
handling in subprograms ® 17-20 to 17-22 
handling RMS ® 17-17 
handling VMS ® 17-16 
in a function® 17-24 
NOTBASIC ® 17-12 
OPTION HANDLE statement ® 17-12 
pending ® 17-2, 17-19 
run-time ® 17-1 
severity levels ® 17-12 
severity of © 17-1 
trapping ® 17-1 to 17-26 
types of ® 17-1 
Error trapping ® 17-1 to 17-26 
ERT$ function ® 17-15 
EVALUATE debugger command ® 5-19 
EVE interface ® 4-3 
EXAMINE debugger command ® 5-18 
Exception handling ® 17-1 to 17-26 
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Exclamation point (!) © 6-8 
Execution 
start/resume in debugging ® 5-11 
EXIT command ® 3-20 
EXIT debugger command ® 5-6 
EXIT FUNCTION statement ® 14-4 
specifying expression with ® 14-4 
EXIT HANDLER statement ® 17-10 
EXIT PROGRAM statement ® 14-12 
EXIT statement ® 11-16 to 11-18 
EXIT SUB statement ® 14-3 
EXP function ® 12-5 
Explicit data typing ® 9-3 
Exponential format 
with asterisk-fill ® 16-13 
with PRINT USING statement ® 16-12 
Expression 
See also Address expression 
See also Language expression 
Expressions ® 6-17 
mixed-mode ® 9-9 
Extended fields 
with PRINT USING statement ® 16-19 
Extensible VAX Editor(EVE) ® 4-3 
External routines 
calling ® 21-6, 21-8 
declaring ® 21-6 
EXTERNAL statement ® 9-8, 14-4, 14-5, 21-7 
specifying data type of parameters ® 14-5 
specifying data type of return value ® 14-4, 
14-5 
specifying parameter-passing mechanism in ® 
14-5 
type checking with ® 14-6 
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File name 

specifying in the OPEN statement ® 20-1 
File operations ® 15-12 
File organization ® 15-3 

indexed ® 15-4 

relative © 15-4 

sequential ® 15-3 

terminal-format ® 15-3 

virtual ® 15-5 


‘ile organization (cont’d.) 
virtual © 15-5 
‘iles 
appending ® 4-5 
closing ® 15-33 
deleting ® 2-10 
deleting with KILL statement ® 15-34 
displaying ® 2-8 
file-related functions ® 15-34 to 15-37 
including ® 18-7 
opening with OPEN statement ® 15-12 
printing ® 2-10 
purging ® 2-11 
renaming and moving ® 2-11 
renaming with NAME...AS statement ® 15-33 
restoring ® 15-32 
searching ® 2-12 
setting protection ® 2-12 
transferring data to ® 15-31 
truncating with SCRATCH statement ® 15-32 
typing ® 2-10 
‘ile specification 
example of ® 2-5 
ILL formats ® 9-18 
ILL items ® 9-17 
IND statement ® 15-16 to 15-17 
random access ® 15-16 
sequential ® 15-16 
ixed-length strings ® 13-1 
changing ® 13-4 
using ® 13-4 
IXED record formats 
specifying ® 20-2 
IX function ® 12-3 
loating-point 
variables ® 6-13 
loating-point data ® 9-4 
loating-point numbers 
displaying with PRINT USING statement ® 16-1 
OR...NEXT loops ® 11-4 to 11-7 
ORMATS function ® 12-9 
ormat characters 
‘with PRINT USING statement ® 16-7 
ormat fields 
with PRINT USING statement ® 16-2 
ormat. strings 
with PRINT USING statement ® 16-2 


Formatting characters 


with PRINT statement ® 7-11 
FOR modifier ® 11-1 
FOR statement 
in immediate mode statements ® 3-7 
FORTRAN 
arrays ® 21-10 
FREE statement ® 15-26 
FSP$ function ® 15-34 
FUNCTION ® 14-4 to 14-5 
Function call® 21-6 
Functions ® 12-1 to 12-27 
built-in ® 12-1 
date and time ® 12-15 to 12-17 
string arithmetic ® 12-11 to 12-15 
terminal control ® 12-17 
creating with DEF ® 12-20 to 12-27 
data conversion ® 12-7 
declaring ® 12-23 
external ® 14-4 
file-related ® 15-34 to 15-37 
naming ® 12-20, 12-22, 12-23 
numeric string ® 12-9 
parameter data types ® 12-2 
recursion in® 12-25 
resultant data type ® 12-2 
string arithmetic ® 12-12 
precision of ® 12-12 
FUNCTION subprograms ® 14-2 
running in the environment ® 14-5 
specifying a data type for® 14-11 


GETRFA function ® 15-30 

GET statement ® 15-18 to 15-20, 20-5 
current and next record pointers after ® 15-18 
reading data ® 20-14 
reading records with ® 20-10 
sequential ® 15-18 
with REGARDLESS clause ® 15-27 
with WAIT clause ® 15-20 

Global symbols 
assignment operations ® 2-14 to 2-16 

GO debugger command ® 5-11 

GROUP clause ® 10-5 to 10-9 


index—7 


Handler 

attached @ 17-5 

detached ® 17-5 

exiting from ® 17-7 
Handler priorities ® 17-10, 17-20, 17-26 
Header information 

IDENTIFY command ® 3-21 

omitting with RUNNH command ® 3-25 
Help 

online ® 5-3 
HELP command ® 2-3, 3-20 
HELP debugger command ® 5-3, 5-4 
HELP facility 

accessing ® 2-3 


1/0 
device-specific © 20-7 
performing to ANSI-formatted magnetic tapes ® 
20-2 
to mailboxes ® 20-14 
1/O buffer ® 15-6 
%IDENT directive ® 18-4 
IDENTIFY command ® 3-21 
IF... THEN...ELSE statement ® 11-12 to 11-13 
%IF-%THEN-%ELSE-%END %IF directive ® 18-9, 
18-11 
IF modifier ® 11-1 
IF statement 
in immediate mode statements ® 3-7 
Immediate mode ® 3-5 to 3-9 
debugging in ® 3-8 to 3-9 
debugging multiple program units ® 3-8 
debugging restrictions ® 3-8 
examining variables in ® 3-5 
FOR statement in ® 3-7 
IF statement in ® 3-7 
invalid statements ® 3-7 
UNLESS statement in ® 3-7 
UNTIL statement in ® 3-7 
WHILE statement in ® 3-7 
Implicit data typing® 9-3 
%INCLUDE %FROM %CDD directive ® 23-2, 24-7 
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%INCLUDE directive ® 9-20, 18-7 
accessing record definitions ® 18-7 
accessing text libraries ® 18-7 
benefits of ® 18-9 
from a file ® 18-7 

Indexed files ® 15-4 
alternate index keys ® 15-4 
index key values ® 15-4 

Informational errors © 17-1 

Initialization 
debugger ® 5-5 

Initialization of variables ® 6-15 

INKEY$ function ® 12-19 

Input ® 7-1 to 7-10 
from source program ® 7-7 to 7-10 
from terminal ® 7-5 
from terminal-format files ® 7-5, 7-16 to 7-18 
interactive ® 7-1 
methods for receiving ® 7-1 
strings ® 7-4 to 7-5 

INPUT LINE statement ® 7-4 to 7-5, 7-16 
disabling the prompt ® 7-5 to 7-6 
with strings ® 13-3 

INPUT statement ® 7-2 to 7-4, 7-16 
disabling the prompt ® 7-5 to 7-6 
with strings ® 13-3 

Instance 
RECORD ® 10-1 

Integer 
variables ® 6-14 

INTEGER data type ® 6-9, 9-4 

Integer format 
byte-length ® 19-1 
longword ® 19-2 
word-length ® 19-2 

Interrupt 
debugging session ® 5-6 

INT function ® 12-3 

INV function ® 8-25 

Invoking 
debugger ® 5-5 

ITERATE statement ® 11-16 to 11-18 


Keypad mode ® 4-1 
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Labels ® 6-4 
Language expression 
EVALUATE debugger command ® 5-19 
with DEPOSIT debugger command ® 5-19 
LBOUND function ® 8-8 
Leading zeros 
with PRINT USING statement ® 16-14 
Left-justified format 
with PRINT USING statement ® 16-17 
LEN function 
string function ® 13-11 
%LET directive ® 18-9, 18-10 
LET statement ® 8-9, 8-10 
with dynamic strings ® 13-2 
with string data ® 13-6 
Lexical constants 
creating ® 18-10 
Lexical expressions 
variations of ® 18-10 
Libraries 
object module ® 22-1 
shareable image ® 22-1 
system-supplied ® 22-1, 22-2 
user-supplied ® 22-1, 22-3 
Line mode ® 3-2, 3-5, 4-1 
line numbers in ® 3-5 
Line number 
debugger source display ® 5-10 
SET BREAK debugger command ® 5-14 
SET TRACE debugger command ® 5-16 
Line numbers ® 6-1 
generating ® 3-27 
programs without ® 6-1 
with %INCLUDE directive ® 18-8 
with SEQUENCE command ® 3-27 
/LUINE qualifier ® 5-16 
Lines 
displaying with LIST command ® 3-22 
displaying with LISTNH command ® 3-22 
Line terminator 
accepting as input ® 7-4 
LINK command ® 4-32 
qualifiers of ® 4-33 
Linker 
error messages ® 4-37 


Linker (cont’d.) 
input files ® 4-35 
output files ® 4-35 
Linking 
/DEBUG ® 5-4 
LINPUT statement ® 7-4 to 7-5, 7-16 
disabling the prompt ® 7-5 to 7-6 
with strings ® 13-3 
List © 8-1 
LIST command ® 3-22 
%LIST directive ® 18-5 
/LISTING ® 4-15 
Listing 
compilation ® 4-15 
cross-reference ® 4-25 
source program ® 4-23 
storage map ® 4-27 
LISTNH command ® 3-22 
LOAD command ® 3-8, 3-22 
Local symbols 
assignment operations ® 2-14 
LOC function ® 21-9 
LOCK command ® 3-23 
LOG 10 function ® 12-4 
Logarithms 
common ® 12-4 
Logging in® 2-1, 2-2 
Logical names 
assigning with ASSIGN command ® 3-14 
defining ® 2-15, 15-14 
example of ® 15-14 
using ® 15-14 
LOGIN.COM file 
example of ® 2-19 
LOGOUT command ® 2-2 
LONG data type ® 6-9 
subtypes ® 6-9 
Loop blocks ® 11-4 
Loop control variable ® 11-4 
Loop index ® 11-4 
Loops ® 11-4 to 11-10 
FOR...NEXT ® 11-4 to 11-7 
UNTIL...NEXT ® 11-8 
WHILE...NEXT ® 11-7 to 11-8 
Lower bounds 
with COMMON statement ® 9-14 
with DECLARE statement ® 9-6 
with MAP statement ® 9-14 
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Lower bounds (cont’d.) 


with the RECORD statement ® 10-4 
LSET statement 

concatenating strings ® 13-2 

with dynamic strings ® 13-2 

with string data ® 13-7 


Magnetic tape blocksizes ® 20-5 
Magnetic tape file 
creating for output ® 20-9 
Magnetic tape files 
creating ® 20-2 
existing ® 20-3 
opening ® 20-2, 20-9 
Mailboxes 
creating ® 20-15 
passing data between processes ® 20-14 
Map area 
defining ® 9-19 
MAP DYNAMIC statement ® 9-21 
Maps 
multiple ® 9-16 
single ® 9-15 
MAP statement ® 8-7, 9-14 
overlaying array storage with ® 8-7 
with subprograms ® 9-19 
MAT INPUT statement ® 8-16 
continuing input line with ampersand @ 8-18 
filling array elements with ® 8-17 
from a terminal ® 8-16 
from a terminal-format file © 8-16 
prompt character ® 8-17 
subscripts in ® 8-16 
MAT LINPUT statement ® 8-18 
filling array elements with ® 8-18 
redimensioning arrays with ® 8-19 
MAT PRINT statement ® 8-19 
with comma ({,) ® 8-20 
with semicolon (;) ® 8-20 
MAT READ statement ® 8-15 
subscripts in ® 8-15 
with DATA statement ® 8-16 
Matrix ® 8-1 
arithmetic ® 8-22 
functions ® 8-24 to 8-26 
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MAT statement ® 8-5, 8-13 
adding elements of arrays ® 8-22 
assigning array values from other arrays ® 8-22 
assigning values with ® 8-11 
creating arrays with ® 8-14 
displaying values with ® 8-11 
for array computations ® 8-21 to 8-26 
keywords ® 8-13 
multiplying elements of arrays ® 8-23 
redimensioning with ® 8-14 
subscripts in ® 8-14 
subtracting elements of arrays ® 8-22 
use of row and column zero ® 8-12 
with implicitly created arrays ® 8-12 
MAT statements ® 8-11 to 8-20 
Memory 
clearing with NEW command ® 3-23 
clearing with SCRATCH command ® 3-27 
Merge 
APPEND command ® 3-10 
MIDS 
assignment statement ® 13-10 
MID$ function 
string function ® 13-16 
Mixed-mode expressions ® 9-9 
Mode 
immediate ® 3-5 
line ® 3-2, 3-5 
Modifiers 
statement ® 11-1 to 11-3 
Module 
setting ® 5-22 
Module names ® 6-6, 14-11 
MOVE statement ® 15-7, 15-10 to 15-11 
default string lengths ® 15-10 
valid variables in ® 15-10 
Multiplication of matrices ® 8-23 
Multiplier block © 19-11 


NAME clause (CDDL) ® 23-6 
Names 
variables ® 6-13 
Negative format fields 
with PRINT USING statement ® 16-12 
Network I/O ® 20-16 





2gative format fields 
with PRINT USING statement ® 16-12 
2twork 1/0 ® 20-16 
:W command ® 3-3, 3-23 
2»xt record pointer ® 15-6 
NOCROSS directive ® 18-6 
JECHO function ® 12-18 
okeypad mode ® 4- 1 
JOLINE 
with ERL function ® 17-14 
NOLIST directive ® 18-5 
nprinting characters ® 6-7 
JREWIND 
positioning tape ® 20-3 
JTBASIC errors ® 17-16 to 17-18 
ul 
character ® 13-4 
string ® 13-4 
JM1$ function ® 12-10 
JMS function ® 12-9 
imbers 
printing with PRINT USING statement ® 16-4 
imeric data 
interpreting with multiple maps ® 9-17 
JM function ® 8-2 1 


yect module libraries 

at DCL level ® 22-4 

creating ® 22-3 

module names in ® 6-6 

within the BASIC environment ® 22-3 

ect module library 

using ® 4-36 

ject modules ® 3-9 

loading with LOAD command ® 3-22 
producing with /OBJECT ® 4-11 
LD_VERSION=CDD_ARRAYS ® 4-12 

D command ® 3-2, 3-8, 3-24 

| ERROR GO BACK statement ® 17-24 

| ERROR GOTO statement ® 17-24 

passing to default error handler ® 17-24 

| ERROR statement ® 17-23, 17-23 to 17-26 
EN statement ® 7-17, 15-12 

BUCKETSIZE ® 15-37 

clauses for optimizing I/O ® 15-37 to 15-46 


OPEN statement (cont'd.) 


control structures set by USEROPEN keyword ® 
15-44 
EXTENDSIZE clause ® 15-41 
FOR INPUT ® 15-12 
FOR OUTPUT ® 15-12 
opening indexed files ® 15-14 
ORGANIZATION UNDEFINED ® 15-34 
RECORDSIZE ® 15-13 
RECORDTYPE ANY ® 15-34 
specifying file characteristics with ® 15-13 
UNLOCK EXPLICIT ® 15-26 
with BUFFER clause ® 15-39 
with CONNECT clause ® 15-39 
with CONTIGUOUS clause ® 15-40 
with DEFAULTNAME clause ® 15-41 
with FILESIZE clause ® 15-42 
with MAP clause ® 15-13 
with NOSPAN clause ® 15-42 
with RECORDTYPE clause ® 15-43 
with TEMPORARY clause ® 15-43 
with USEROPEN keyword ® 15-44 
with WINDOWSIZE attribute ® 15-46 
Operand ® 6-17 
Operator ® 6-17 
Optimization 
with handlers ® 17-9 
OPTION HANDLE statement ® 17-12 
OPTION statement ® 3-14 
Output ® 7-11 to 7-16 
displaying with PRINT statement ® 7-10 
format for numbers ® 7-14 
format for strings ® 7-14 to 7-16 
to terminal-format files ® 7-16 to 7-18 
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Packed decimal 
data type ® 6-9 
variables ® 6-14 
Packed decimal format ® 19-6 
Packed Decimal string descriptors ® 19-12 
%PAGE directive ® 18-5 
Parameter-passing mechanisms ® 21-2 to 21-5 
declaring in EXTERNAL statement ® 14-5 
default © 21-3 
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Parameters 


creating local copies of ® 21-5 to 21-6 
default data types for ® 14-7 
null ® 21-8 
passing BY DESC ® 21-2 
passing BY REF ® 21-2 
passing BY VALUE ® 21-3 
Password 
changing ® 2-2 
Path Name ® 24-4 
in debugging ® 5-8, 5-12, 5-14, 5-23 
PC 
and SHOW CALLS debugger display ® 5-12 
and source display ® 5-9 
and STEP debugger command ® 5-12 
breakpoint ® 5-14 
PICTURE subprograms ® 14-2 
PLACE$ function ® 12-14 
precision of ® 12-13 
significant digits ® 12-12 
Placeholders 
reserving with PRINT USING statement ® 16-4 
POS function 
string function ® 13-12 
Positional qualifiers 
rules for precedence ® 4-5 
Predefined constants 
BEL ® 6-12 
BS ®6-12 
CR® 6-12 
DEL ® 6-12 
ESC ® 6-12 
FFe®6-12 
HT ® 6-12 
LF e® 6-12 
Pl@6-12 
Sl¢ 6-12 
SO ® 6-12 
SP ® 6-12 
VT ®6-12 
PRINT command ® 2-10 
%PRINT directive ® 18-11 
PRINT statement ® 7-10, 7-16 
expression values ® 7-10 
for array elements ® 8-11 
string literals ® 7-10 
with comma ® 7-11 
with semicolon ® 7-12 
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PRINT USING statement ® 16-1 
Print zones ® 7-11 to 7-14 
Priorities of handlers ® 17-20 
Procedure call® 21-6 
PROD$ function ® 12-15 
precision of ® 12-13 
significant digits ® 12-12 
Program control ® 11-1 to 11-18 
Program execution 
resuming with CONTINUE command ® 3-18 
Programs 
comments ® 6-8 
controlling ® 11-1 to 11-18 
documenting ® 6-7 
naming ® 6-6 
renaming with RENAME command ® 3-24 
renumbering with RESEQUENCE command ® 
3-25 
PROGRAM statement ® 6-5, 14-11 to 14-12 
identifiers © 6-6, 14-11 
Prompt 
debugger (DBG> )® 5-5 
enabling and disabling ® 7-5 
Protected regions ® 17-2, 17-3 
nested ® 17-10 to 17-11 
Prototype block ® 19-10 
PURGE command ® 2-11 
PUT statement ® 15-20 to 15-22, 20-4 
current and next record pointers after ® 15-20 
sequential ® 15-20 
writing data ® 20-13 
writing records with ® 20-10 


qualifier 
/VARIANT ® 18-10 
QUO$ function 
precision of ® 12-13 
significant digits ® 12-12 


RANDOMIZE statement ® 12-6 
Random number generator ® 12-6 
selecting range ® 12-6 
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NEW command ® 3-3, 3-23 
Next record pointer ® 15-6 
%NOCROSS directive ® 18-6 
NOECHO function ® 12-18 
Nokeypad mode ® 4-1 
/NOLINE 

with ERL function ® 17-14 
%NOLIST directive ® 18-5 
Nonprinting characters ® 6-7 
NOREWIND 

positioning tape ® 20-3 
NOTBASIC errors ® 17-16 to 17-18 
Null 

character ® 13-4 

string ® 13-4 
NUM1$ function ® 12-10 
NUM$ function ® 12-9 
Numbers 

printing with PRINT USING statement ® 16-4 
Numeric data 

interpreting with multiple maps ® 9-17 
NUM function ® 8-21 


Object module libraries 
at DCL level ® 22-4 
creating ® 22-3 
module names in ® 6-6 
within the BASIC environment ® 22-3 
Object module library 
using ® 4-36 
Object modules ® 3-9 
loading with LOAD command ® 3-22 
producing with /OBJECT ® 4-11 
/OLD_.VERSION=CDD_ARRAYS ® 4-12 
OLD command ® 3-2, 3-8, 3-24 
ON ERROR GO BACK statement ® 17-24 
ON ERROR GOTO statement ® 17-24 
passing to default error handler ® 17-24 
ON ERROR statement ® 17-23, 17-23 to 17-26 
OPEN statement ® 7-17, 15-12 
BUCKETSIZE ® 15-37 
clauses for optimizing I/O ® 15-37 to 15-46 
control structures set by USEROPEN keyword ® 
15-44 
EXTENDSIZE clause ® 15-41 





OPEN statement (cont’d.) 
FOR INPUT ® 15-12 
FOR OUTPUT ® 15-12 
opening indexed files ® 15-14 
ORGANIZATION UNDEFINED ® 15-34 
RECORDSIZE ® 15-13 
RECORDTYPE ANY ® 15-34 
specifying file characteristics with ® 15-13 
UNLOCK EXPLICIT ® 15-26 
with BUFFER clause ® 15-39 
with CONNECT clause ® 15-39 
with CONTIGUOUS clause ® 15-40 
with DEFAULTNAME clause ® 15-41 
with FILESIZE clause ® 15-42 
with MAP clause ® 15-13 
with NOSPAN clause ® 15-42 
with RECORDTYPE clause ® 15-43 
with TEMPORARY clause ® 15-43 
with USEROPEN keyword ® 15-44 
with WINDOWSIZE attribute ® 15-46 
Operand ® 6-17 
Operator ® 6-17 
Optimization 
with handlers ® 17-9 
OPTION HANDLE statement ® 17-12 
OPTION statement ® 3-14 
Output ® 7-10 to 7-16 
displaying with PRINT statement ® 7-10 
format for numbers ® 7-14 
format for strings ® 7-14 to 7-16 
to terminal-format files © 7-16 to 7-18 
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Packed decimal 
data type ® 6-9 
variables ® 6-14 
Packed decimal format ® 19-6 
Packed Decimal string descriptors ® 19-12 
%PAGE directive ® 18-5 
Parameter-passing mechanisms ® 21-2 to 21-5 
declaring in EXTERNAL statement ® 14-5 
default ® 21-3 
Parameters 
creating local copies of ® 21-5 to 21-6 
default data types for ® 14-7 
null ® 21-8 
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Parameters (cont'd.) 

passing BY DESC ® 21-2 

passing BY REF ® 21-2 

passing BY VALUE ® 21-3 
Password 

changing ® 2-2 
Path name 

in debugging ® 5-8, 5-12, 5-14, 5-23 
PC 

and SHOW CALLS debugger display ® 5-12 

and source display ® 5-9 

and STEP debugger command ® 5-12 

breakpoint ® 5-14 
PICTURE subprograms ® 14-2 
PLACE$ function ® 12-14 

precision of ® 12-13 

significant digits ® 12-12 
Placeholders 

reserving with PRINT USING statement ® 16-4 
POS function 

string function ® 13-12 
Positional qualifiers 

rules for precedence ® 4-5 
Predefined constants 

BEL® 6-12 

BS ®6-12 

CR®6-12 

DEL ® 6-12 

ESC ®6-12 

FF ®6-12 

HT ®6-12 

LF®6-12 

Pl® 6-12 

S!1°6-12 

SO °® 6-12 

SP ®6-12 

VT ®6-12 
PRINT command ® 2-10 
%PRINT directive ® 18-11 
PRINT statement ® 7-10, 7-16 

expression values ® 7-10 

for array elements ® 8-11 

string literals ® 7-10 

with comma ® 7-114 

with semicolon ® 7-12 
PRINT USING statement ® 16-1 
Print zones ® 7-11 to 7-14 
Priorities of handlers ® 17-20 
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Procedure call ® 21-6 
PROD$ function ® 12-15 
precision of ® 12-13 
significant digits ® 12-12 
Program control® 11-1 to 11-18 
Program execution 
resuming with CONTINUE command ® 3-18 
Programs 
comments ® 6-8 
controlling ® 11-1 to 11-18 
documenting ® 6-7 
naming ® 6-6 
renaming with RENAME command ® 3-24 
renumbering with RESEQUENCE command ® 
3-25 
PROGRAM statement ® 6-5, 14-11 to 14-12 
identifiers ® 6-6, 14-11 
Prompt 
debugger (DBG> )®5-5 
enabling and disabling ® 7-5 
Protected regions ® 17-2, 17-3 
nested ® 17-10 to 17-11 
Prototype block ® 19-10 
PURGE command ® 2-11 
PUT statement ® 15-20 to 15-22, 20-4 
current and next record pointers after ® 15-20 
sequential ® 15-20 
writing data ® 20-13 
writing records with ® 20-10 


qualifier 
/VARIANT ® 18-10 
QUO$ function 
precision of ® 12-13 
significant digits ® 12-12 


RANDOMIZE statement ® 12-6 

Random number generator ® 12-6 
selecting range ® 12-6 

Random number generators 
changing seed ® 12-6 

RCTRLC function ® 12-17, 17-19 

READ statement ® 7-7 to 7-9 


REAL data type ® 6-9 
Real number format 
DOUBLE floating-point ® 19-4 
GFLOAT floating-point ® 19-5 
HFLOAT floating-point ® 19-6 
SINGLE floating-point ® 19-3 
Record buffer ® 15-6 
Record buffers 
accessing with multiple maps ® 9-16 
dynamic ® 15-7 
static ® 15-6 
RECORD components ® 10-1 
accessing ® 10-9 to 10-14 
fully qualified ® 10-9 
grouping ® 10-5 
referencing ® 10-2, 10-9 
Record File Address ® 15-29 
Record formats ® 15-1 to 15-2 
RECORD instances ® 10-1 
arrays of ® 10-3 
Record operations ® 15-12 
Records 
blocking and deblocking of ® 20-6 
writing to a terminal-format file ® 7-17 
writing with PUT and GET statements ® 20-4 
RECORD statement ® 10-1 to 10-14 
RECORD templates ® 10-1 
RECORD variants ® 10-6 to 10-9 
RECOUNT function ® 15-36 
Relative files ® 15-4 
REMAP statement ® 9-22 
Remote files 
accessing ® 20-17 
RENAME command ® 2-11, 3-24 
REPLACE command ® 3-25 
RESEQUENCE command ® 3-25 
RESTORE statement ® 7-9 
rewinding tape with ® 20-7 
with magnetic tapes ® 20-11 
RESUME statement ® 17-8, 17-25 to 17-26 
to a label® 17-25 
to a line number ® 17-25 
Retrieval pointers ® 15-46 
RETRY statement ® 17-8 
RFA data type ® 6-9 
Right justification 
RSET statement ® 13-8 


Right-justified format 

with PRINT USING statement ® 16-18 
RMSSTATUS function ® 15-36 to 15-37, 17-17 
RND function ® 12-6 
Round-off errors 

overcoming with SCALE command ® 3-27 
RSET statement 

concatenating strings ® 13-2 

with dynamic strings ® 13-2 

with string data ® 13-8 
RST (run-time symbol table) ® 5-22 
RUN command ® 3-2, 3-3, 3-9, 3-25, 4-38, 5-5 
RUNNH command ® 3-2, 3-3, 3-25 
Run-time errors ® 17-1 to 17-26 
Run-Time Library routines ® 21-11 


SAVE command ® 3-3, 3-26 
%SBTTL directive ® 18-3 
SCALE command ® 3-27 
Scope 
debugging ® 5-23 
SCRATCH command ® 3-27 
Screen mode ® 5-8 
SEARCH command ® 2-12 
SEG$ function 
string function ® 13-14 
SELECT...CASE statement ® 11-14 to 11-16 
with RECORD variants ® 10-6 
Semicolons 
using with PRINT statement ® 7-12 
SEQUENCE command ® 3-27 
Sequential files ® 15-3 
SET [NO] PROMPT statement ® 7-5 to 7-6, 8-17 
SET BREAK debugger command ® 5-13 
SET command ® 3-28 
SET DEFAULT command ® 2-6 
SET MODE [NO]DYNAMIC debugger command ® 
5-23 
SET MODE SCREEN debugger command ® 5-8 
SET MODULE debugger command ® 5-22 
SET NO PROMPT statement 
disabling the prompt ® 7-6 
SET PASSWORD command ® 2-2 
SET PROTECTION command ® 2-12 
SET SCOPE debugger command ® 5-24 
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SET TRACE debugger command ® 5-15 
SET VARIANT command ® 18-10 
Severe errors ® 17-1 
Shareable images ® 22-5 
accessing ® 22-5 
accessing at DCL level ® 22-7 
benefits of ® 22-5 
contents of ® 22-1 
creating ® 22-5 
installed ® 22-1 
within the BASIC environment ® 22-6 
/SHARE qualifier ® 5-16 
SHOW CALLS debugger command ® 5-12 
SHOW command ® 3-28 
SHOW MODULE debugger command ® 5-22 
SHOW SCOPE debugger command ® 5-24 
SHOW SYMBOL debugger command ® 5-23 
/SILENT qualifier © 5-16 
SIN function ® 12-3 
Single tape file 
example of creating ® 15-45 
Source display ® 5-8, 5-9 
not available © 5-10 
TYPE debugger command ® 5-8 
Source program listing ® 4-23 
Source programs 
compiling ® 2-21 
creating ® 2-21 
linking ® 2-21 
SPACE$ function 
string function ® 13-18 
Statement modifiers ® 11-1 to 11-3 
FOR ® 11-1 
IFe 11-1 
UNLESS ® 11-1 
UNTIL ® 11-1 
WHILE ® 11-1 
Static storage ® 6-11 
allocating © 9-12 
dynamic mapping ® 9-21 
SSTATUS ® 14-11 
Status 
on exit ® 14-11 
STATUS function ® 15-36 to 15-37 
STEP clause ® 11-4 
STEP debugger command ® 5-11 
STOP statement ® 3-5, 3-8 
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STOP statement (cont’d.) 


resuming program execution after ® 3-8 
Storage 
dynamic ® 6-11 
redefining ® 9-20 
static © 6-11 
Stream record format ® 15-2 
String 
dynamic ® 13-1 
fixed-length ® 13-1 
manipulating with multiple maps ® 9-16 
numeric ® 12-9 
variable ® 6-14 
virtual array ® 13-1 
STRINGS function 
string function ® 13-17 
String data 
assigning and justifying ® 13-6 
formatting with PRINT USING statement ® 16-2 
manipulating with MAP statements ® 13-20 
manipulating with string functions ® 13-11 
STRING data type ® 6-9 
String format fields ® 16-16 
String function 
EDITS function ® 13-19 
LEN function ® 13-11 
MID$ function ® 13-16 
POS function ® 13-12 
purposes ® 13-11 
SEG$ function ® 13-14 
SPACES function ® 13-18 
STRING$ function ® 13-17 
TRM$§ function ® 13-18 
with the LET statement ® 13-11 
Strings 
printing with PRINT USING statement ® 16-15 
String variables 
fixed-length ® 13-1 
String virtual arrays 
assigning values ® 13-5 
creating ® 13-5 
Subdirectories 
creating ® 2-6 
deleting ® 2-8 
Subprograms ® 14-2 
calling from other languages ® 21-9 
compiling ® 14-8 to 14-9 
compiling from a single source file ® 14-8 


Subprograms ({cont’d.) 


compiling from multiple source files ® 14-8 
creating a single object file® 14-8 
DATA statements in® 14-3 
handling errors in® 17-20 to 17-22 
invoking ® 14-10 to 14-11 
passing data to ® 14-6 
READ statements in ® 14-3 
RESTORE statements in ® 14-3 
Subscripted variables ® 6-13, 6-15 
SUB subprograms ® 14-2 to 14-4 
Subtraction of matrices ® 8-22 
Subtypes 
numeric ® 9-4 
SUMS$ function 
precision of ® 12-13 
Symbol 
record ® 5-4 
Symbolic debugger 
see Debugger 
Symbolic definitions ® 21-19 
accessing with %INCLUDE directive ® 21-20 
location of ®21-19 
Symbols 
assignment operations ® 2-14 
/SYSTEM qualifier ® 5-16 
System routines 
arguments of ®21-13 
calling ® 21-11 
calling as a procedure ® 2 1-7 
examples of calling ® 21-21 
System Service routines ® 21-12 
System services 
example of calling ® 21-21 


T 


TAN function ® 12-3 
Tapes 
allocating ® 20-2 
setting the density ® 20-2 
Tape unit 
allocating for device-specific |/O © 20-8 
Template 
RECORD ® 10-1 
Terminal-format files ® 15-3 
channel specification for ® 7-17 


Terminal-format files (cont’d.) 
closing ® 7-17 
input and output ® 7-16 to 7-18 
opening ® 7-17 
transferring data to ® 15-31 
writing records to ® 7-17 
Text libraries 
accessing ® 18-8 
creating ® 18-8 
system-supplied ® 18-8 
THEN clause ® 11-12 
TIME$ function ® 12-16 
TIME function ® 12-17 
% TITLE directive ® 18-3 
Traceback 
SHOW CALLS debugger command ® 5-12 
Tracepoint ® 5-15 
TRM$ function 
string function ® 13-18 
TRN function ® 8-24 
TYPE command ® 2-10 
TYPE debugger command ® 5-8 


UBOUND function ® 8-8 
UNLESS modifier ® 11-1 
UNLESS statement 
in immediate mode statements ® 3-7 
UNLOCK EXPLICIT clause ® 15-26 
UNLOCK statement ® 15-26 
UNSAVE command ® 3-30 
UNTIL...NEXT loops ® 11-8 
UNTIL modifier ® 11-1 
UNTIL statement 
in immediate mode statements ® 3-7 
UPDATE statement ® 15-23 to 15-25 
current and next record pointers after ® 15-24 
in an indexed file © 15-24 
in a relative file ® 15-24 
in a sequential file® 15-23 
Upper bounds 
with COMMON statement ® 9-14 
with DECLARE statement ® 9-6 
with MAP statement ® 9-14 
with the RECORD statement ® 10-4 
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VAL% function® 12-11 
VAL function ® 12-11 
Variable name 
DEPOSIT debugger command ® 5-19 
EVALUATE debugger command ® 5-19 
EXAMINE debugger command ® 5-18 
VARIABLE record formats 
specifying ® 20-2 
Variables ® 6-13 
arrays of ® 6-13, 6-15 
declaring ® 6-9 
floating-point ® 6-13 
initialization of ® 3-7, 6-15 
integer ® 6-14 
names ® 6-13 
packed decimal ® 6-14 
redefining ® 9-20 
string ® 6-14, 13-1 
subscripted ® 6-13, 6-15 
VARIANT ® 10-6 to 10-9 
Variant 
CDD ® 23-9 
%VARIANT directive ® 18-9, 18-10 
VAX/VMS Debugger 


see Debugger 
VAX/VMS Symbolic Debugger 


see Debugger 
VAX Procedure Calling Standard ® 21-9 
VAXTPU 
using ® 4-2 
Vector ® 8-1 
Virtual array files ® 15-15 
Virtual files © 15-5 
VMS data structures 
table of ©21-14 
VMSSTATUS function ® 15-36 to 15-37, 17-16 


Ww 


WAIT clause ® 15-27 

Warning errors ® 17-1 

WHEN ERROR constructs ® 17-2 to 17-23 
attached handler ® 17-2 
CONTINUE to target ® 17-9 
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WHEN ERROR constructs (cont’d.) 
exiting handler ® 17-7 
nested ® 17-10 to 17-11 
protected region ® 17-2 
with CONTINUE statement ® 17-9 
with EXIT HANDLER statement ® 17-10 
with RETRY statement ® 17-8 
WHILE...NEXT loops ® 11-7 to 11-8 
WHILE modifier ® 11-1 
WHILE statement 
in immediate mode statements ® 3-7 
Wildcard characters ® 2-9, 2-10 
WORD data type ® 6-9 
subtypes ® 6-9 


Z 


Zero-fill 
with asterisk-fill ® 16-14 


How to Order Additional Documentation 





Technical Support 


If you need help deciding which documentation best meets your needs, call 800-343-4040 
before placing your electronic, telephone, or direct mail order. 


Orders 


To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using 
a 1200- or 2400-baud modem. If you need assistance using the Electronic Store, 
call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Your Location Call Contact 
Continental USA, 800-DIGITAL Digital Equipment Corporation 
Alaska, or Hawaii P.O. Box CS2008 

Nashua, New Hampshire 03061 
Puerto Rico 809-754-7575 Local DIGITAL subsidiary 
Canada 800-267-6215 Digital Equipment of Canada 


Attn: DECdirect Operations KAOQ2/2 
P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 


International 2 2 —— — — ——— Local DIGITAL subsidiary or 
. approved distributor 
Internal) SDC Order Processing - WMO/E15 


or 

Software Distribution Center 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 


'For internal orders, you must submit an Internal Software Order Form (EN-01740-07). 
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